This site is routed so that provider selection has exactly one mechanism in the class,
+ * but its fallback can never fire and that is correct, not an oversight: the OpenSearch
+ * implementation is {@code return new OSContentletScrollImpl(...)} — pure construction, no
+ * I/O, nothing to throw. The requests happen later, inside the returned cursor, outside the
+ * router. A mid-scroll fallback is impossible in principle anyway, because an OpenSearch
+ * scroll id is meaningless to Elasticsearch, so a half-drained scroll cannot be resumed on
+ * the other engine. The residual gap is documented at the call site.
+ */
+ @Test
+ public void createScrollQuery_phase2_selectsOsAndDoesNotTouchEs() {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+ final ContentFactoryIndexOperations es = mock(ContentFactoryIndexOperations.class);
+ final ContentFactoryIndexOperations os = mock(ContentFactoryIndexOperations.class);
+ final IndexContentletScroll osScroll = mock(IndexContentletScroll.class);
+ when(os.createScrollQuery(anyString(), any(), anyBoolean(), anyInt(), anyString()))
+ .thenReturn(osScroll);
+
+ final IndexContentletScroll scroll = router(es, os).read(impl ->
+ impl.createScrollQuery("+contentType:Profile", null, false, 100, "title asc"));
+
+ assertSame(osScroll, scroll);
+ verifyNoInteractions(es);
+ }
+
+ /**
+ * Given : Phase 1, where Elasticsearch serves reads.
+ * When : createScrollQuery runs through the router.
+ * Then : the Elasticsearch cursor is returned and OpenSearch is never contacted.
+ */
+ @Test
+ public void createScrollQuery_phase1_selectsEs() {
+ setPhase(MigrationPhase.PHASE_1_DUAL_WRITE_ES_READS);
+ final ContentFactoryIndexOperations es = mock(ContentFactoryIndexOperations.class);
+ final ContentFactoryIndexOperations os = mock(ContentFactoryIndexOperations.class);
+ final IndexContentletScroll esScroll = mock(IndexContentletScroll.class);
+ when(es.createScrollQuery(anyString(), any(), anyBoolean(), anyInt(), anyString()))
+ .thenReturn(esScroll);
+
+ final IndexContentletScroll scroll = router(es, os).read(impl ->
+ impl.createScrollQuery("+contentType:Profile", null, false, 100, "title asc"));
+
+ assertSame(esScroll, scroll);
+ verifyNoInteractions(os);
+ }
+
+ // =========================================================================
+ // The fallback must be a single attempt — a failing read costs one extra
+ // call against ES, with no nesting and no retry storm.
+ // =========================================================================
+
+ /**
+ * Given : Phase 2 with both engines failing on the same read.
+ * When : the read runs through the router.
+ * Then : the Elasticsearch failure surfaces to the caller, and each provider was called
+ * exactly once. A two-engine outage is the one case where a caller now sees an error
+ * where it previously saw an empty result — which is the point of the issue, since
+ * the silent-empty variant is the dangerous one.
+ */
+ @Test
+ public void phase2_bothEnginesFail_surfacesErrorAfterExactlyOneAttemptEach() {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+ final ContentFactoryIndexOperations es = mock(ContentFactoryIndexOperations.class);
+ final ContentFactoryIndexOperations os = mock(ContentFactoryIndexOperations.class);
+ when(os.indexCount(anyString())).thenThrow(unreachable());
+ when(es.indexCount(anyString())).thenThrow(unreachable());
+
+ assertThrows(DotRuntimeException.class,
+ () -> router(es, os).read(impl -> impl.indexCount("+contentType:Profile")));
+
+ verify(os, times(1)).indexCount(anyString());
+ verify(es, times(1)).indexCount(anyString());
+ }
+
+ /**
+ * Given : Phase 2 and a healthy OpenSearch.
+ * When : the read succeeds.
+ * Then : Elasticsearch is never contacted. The fallback must cost nothing on the success
+ * path — otherwise Phase 2 would double every read in the product.
+ */
+ @Test
+ public void phase2_osHealthy_neverTouchesEs() {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+ final ContentFactoryIndexOperations es = mock(ContentFactoryIndexOperations.class);
+ final ContentFactoryIndexOperations os = mock(ContentFactoryIndexOperations.class);
+ when(os.indexCount(anyString())).thenReturn(215L);
+
+ final long count = router(es, os).read(impl -> impl.indexCount("+contentType:Hero"));
+
+ assertEquals(215L, count);
+
+ verify(es, never()).indexCount(anyString());
+ }
+
+ // =========================================================================
+ // The fallback log line (AC-003).
+ //
+ // The pre-fix path logged these failures at WARN, which is why an outage was
+ // invisible to log-based monitoring even though the design documents it as the
+ // early-warning signal. Level is therefore part of the contract, not cosmetic:
+ // a test that only checked "something was logged" would pass against the old
+ // behaviour.
+ // =========================================================================
+
+ /** Captures events published to a single log4j2 logger. */
+ private static final class CapturingAppender extends AbstractAppender {
+
+ private final List events = new ArrayList<>();
+
+ CapturingAppender() {
+ super("capture-phase-router", null, null, true, null);
+ }
+
+ @Override
+ public void append(final LogEvent event) {
+ events.add(event.toImmutable());
+ }
+ }
+
+ private CapturingAppender attachAppender() {
+ final CapturingAppender appender = new CapturingAppender();
+ appender.start();
+ final org.apache.logging.log4j.core.Logger logger =
+ (org.apache.logging.log4j.core.Logger) LogManager.getLogger(PhaseRouter.class);
+ logger.addAppender(appender);
+ return appender;
+ }
+
+ private void detachAppender(final CapturingAppender appender) {
+ final org.apache.logging.log4j.core.Logger logger =
+ (org.apache.logging.log4j.core.Logger) LogManager.getLogger(PhaseRouter.class);
+ logger.removeAppender(appender);
+ appender.stop();
+ }
+
+ /**
+ * Given : Phase 2 and an unreachable OpenSearch.
+ * When : a named read falls back.
+ * Then : exactly one event is logged, at ERROR, naming both the operation that failed and
+ * the cause, with the throwable attached. One event per read — not per provider, and
+ * with no retry storm behind it.
+ */
+ @Test
+ public void phase2_fallback_logsOnceAtErrorNamingOperationAndCause() {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+ final ContentFactoryIndexOperations es = mock(ContentFactoryIndexOperations.class);
+ final ContentFactoryIndexOperations os = mock(ContentFactoryIndexOperations.class);
+ when(os.indexCount(anyString())).thenThrow(unreachable());
+ when(es.indexCount(anyString())).thenReturn(184L);
+
+ final CapturingAppender appender = attachAppender();
+ try {
+ router(es, os).read("indexCount", impl -> impl.indexCount("+contentType:Profile"));
+ } finally {
+ detachAppender(appender);
+ }
+
+ assertEquals("A fallback must log exactly one event per read", 1, appender.events.size());
+ final LogEvent event = appender.events.get(0);
+ assertEquals("The fallback must be ERROR — WARN is what monitoring was missing",
+ Level.ERROR, event.getLevel());
+ final String message = event.getMessage().getFormattedMessage();
+ assertTrue("The log line must name the failing operation, so monitoring can say what "
+ + "stopped working. Was: " + message,
+ message.contains("indexCount"));
+ assertTrue("The log line must carry the cause. Was: " + message,
+ message.contains("Connection refused"));
+ assertNotNull("The throwable must be attached so the stack identifies the call site",
+ event.getThrown());
+ }
+
+ /**
+ * Given : Phase 3 and an unreachable OpenSearch.
+ * When : the read propagates instead of falling back.
+ * Then : no fallback event is logged. A fallback log line in Phase 3 would be a false
+ * signal — there is no fallback there, and Elasticsearch is decommissioned.
+ */
+ @Test
+ public void phase3_failure_logsNoFallbackEvent() {
+ setPhase(MigrationPhase.PHASE_3_OPENSEARCH_ONLY);
+ final ContentFactoryIndexOperations es = mock(ContentFactoryIndexOperations.class);
+ final ContentFactoryIndexOperations os = mock(ContentFactoryIndexOperations.class);
+ when(os.indexCount(anyString())).thenThrow(unreachable());
+
+ final CapturingAppender appender = attachAppender();
+ try {
+ assertThrows(DotRuntimeException.class, () -> router(es, os)
+ .read("indexCount", impl -> impl.indexCount("+contentType:Profile")));
+ } finally {
+ detachAppender(appender);
+ }
+
+ assertEquals("Phase 3 must not report a fallback", 0, appender.events.size());
+ }
+}
diff --git a/dotcms-integration/src/test/java/com/dotcms/MainSuite1b.java b/dotcms-integration/src/test/java/com/dotcms/MainSuite1b.java
index f9332c46ce24..4f1369b8535b 100644
--- a/dotcms-integration/src/test/java/com/dotcms/MainSuite1b.java
+++ b/dotcms-integration/src/test/java/com/dotcms/MainSuite1b.java
@@ -96,6 +96,8 @@
com.dotcms.content.elasticsearch.business.ESIndexSpeedTest.class,
com.dotcms.content.elasticsearch.business.ES6UpgradeTest.class,
com.dotcms.content.elasticsearch.business.ESContentFactoryImplTest.class,
+ com.dotcms.content.elasticsearch.business.ESContentFactoryImplPhase2FallbackTest.class,
+ com.dotcms.content.elasticsearch.business.ESContentFactoryImplMissingOsIndexTest.class,
com.dotcms.graphql.datafetcher.page.ContentMapDataFetcherTest.class,
com.dotcms.graphql.datafetcher.RelationshipFieldDataFetcherTest.class,
com.dotcms.rest.StoryBlockMarkdownPopulatorTest.class,
diff --git a/dotcms-integration/src/test/java/com/dotcms/content/elasticsearch/business/ESContentFactoryImplMissingOsIndexTest.java b/dotcms-integration/src/test/java/com/dotcms/content/elasticsearch/business/ESContentFactoryImplMissingOsIndexTest.java
new file mode 100644
index 000000000000..638a2c343e13
--- /dev/null
+++ b/dotcms-integration/src/test/java/com/dotcms/content/elasticsearch/business/ESContentFactoryImplMissingOsIndexTest.java
@@ -0,0 +1,299 @@
+package com.dotcms.content.elasticsearch.business;
+
+import static com.dotcms.content.index.IndexConfigHelper.MigrationPhase.FLAG_KEY;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.dotcms.content.index.IndexConfigHelper.MigrationPhase;
+import com.dotcms.content.index.domain.SearchHits;
+import com.dotcms.content.index.opensearch.ContentFactoryIndexOperationsOS;
+import com.dotcms.content.index.opensearch.OSClientProvider;
+import com.dotcms.content.index.opensearch.OSQueryCache;
+import com.dotcms.contenttype.model.type.ContentType;
+import com.dotcms.datagen.ContentTypeDataGen;
+import com.dotcms.datagen.ContentletDataGen;
+import com.dotcms.util.IntegrationTestInitService;
+import com.dotmarketing.business.CacheLocator;
+import com.dotmarketing.portlets.contentlet.model.Contentlet;
+import com.dotmarketing.portlets.contentlet.model.IndexPolicy;
+import com.dotmarketing.util.Config;
+import java.util.Optional;
+import org.junit.After;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.opensearch.client.opensearch.OpenSearchClient;
+import org.opensearch.client.opensearch._types.ErrorCause;
+import org.opensearch.client.opensearch._types.ErrorResponse;
+import org.opensearch.client.opensearch._types.OpenSearchException;
+import org.opensearch.client.opensearch.core.CountRequest;
+import org.opensearch.client.opensearch.core.SearchRequest;
+
+/**
+ * Integration tests for the second failure class behind
+ * #37413: an OpenSearch node that is
+ * reachable but answers with an error — chiefly a missing counterpart index (AC-005),
+ * which also covers the reactivated pre-migration backup index scenario.
+ *
+ * Why this is a separate failure class from the routing fix
+ * Routing the read path through the phase router fixes an unreachable OpenSearch: a
+ * connection failure reaches the provider's generic handler and is rethrown as a runtime
+ * exception the router catches. A reachable node answering {@code index_not_found_exception} is
+ * different. That is an {@code OpenSearchException}, which the provider absorbs into a sentinel —
+ * an empty {@code ERROR_HIT} result for a search, {@code -1} for a count. The provider then
+ * reports success, the router sees nothing to catch, and the caller receives a legitimate-looking
+ * empty result. Routing alone does not fix it.
+ *
+ * Why the OpenSearch client is mocked here
+ * An earlier version of this test relied on the container simply having no OpenSearch
+ * counterpart indices. That looked like the real customer scenario but was not: the failure it
+ * produced was dotCMS's own index-name resolution giving up ("Unable to load default versioned
+ * indices"), which is a {@code DotRuntimeException} thrown before the OpenSearch client
+ * is ever called — so it exercised the routing fix again rather than the sentinel branch, and
+ * {@code index_not_found_exception} never appeared once in the run. Mocking the client is what
+ * makes the failure the one AC-005 is actually about.
+ *
+ * Coverage this test cannot give
+ * The scroll path carries a second, independent swallow of the same kind — its own
+ * handler that logs a warning and returns an empty list. It cannot be driven from here: the
+ * scroll resolves its client through CDI rather than through the injected provider, so a mocked
+ * client does not reach it. The fix still covers it; only the behavioural proof is missing, and
+ * that gap is deliberate and recorded rather than silently skipped.
+ *
+ * @author Fabrizzio Araya
+ */
+public class ESContentFactoryImplMissingOsIndexTest {
+
+ private static String query;
+
+ @BeforeClass
+ public static void prepare() throws Exception {
+ IntegrationTestInitService.getInstance().init();
+ final ContentType contentType = new ContentTypeDataGen().nextPersisted();
+ final Contentlet contentlet = new ContentletDataGen(contentType.id())
+ .setPolicy(IndexPolicy.WAIT_FOR).nextPersistedAndPublish();
+ assertTrue("Test setup must produce a persisted contentlet",
+ null != contentlet.getInode());
+ query = "+contentType:" + contentType.variable() + " +live:true";
+ }
+
+ @After
+ public void clearPhase() {
+ Config.setProperty(FLAG_KEY, null);
+ }
+
+ private static void setPhase(final MigrationPhase phase) {
+ Config.setProperty(FLAG_KEY, String.valueOf(phase.ordinal()));
+ }
+
+ /** The 404 a reachable OpenSearch returns when the counterpart index does not exist. */
+ private static OpenSearchException indexNotFound() {
+ return new OpenSearchException(ErrorResponse.of(r -> r
+ .status(404)
+ .error(ErrorCause.of(c -> c
+ .type("index_not_found_exception")
+ .reason("no such index [working_20260101000000.os]")))));
+ }
+
+ /**
+ * An OpenSearch provider whose node is up and answering, but whose counterpart index is gone.
+ * The query cache is mocked empty so every call reaches the client rather than a cached hit —
+ * a cached result would mask the failure exactly the way it masked it in QA.
+ */
+ private static ContentFactoryIndexOperationsOS openSearchMissingIndex() throws Exception {
+ return openSearchMissingIndex(mock(OSQueryCache.class));
+ }
+
+ /** Same, with a caller-supplied cache mock so a test can assert what was written to it. */
+ private static ContentFactoryIndexOperationsOS openSearchMissingIndex(
+ final OSQueryCache queryCache) throws Exception {
+ final OpenSearchClient client = mock(OpenSearchClient.class);
+ when(client.search(any(SearchRequest.class), any())).thenThrow(indexNotFound());
+ when(client.count(any(CountRequest.class))).thenThrow(indexNotFound());
+
+ final OSClientProvider clientProvider = mock(OSClientProvider.class);
+ when(clientProvider.getClient()).thenReturn(client);
+
+ when(queryCache.get(any(SearchRequest.class))).thenReturn(Optional.empty());
+ when(queryCache.get(any(CountRequest.class))).thenReturn(Optional.empty());
+
+ return new ContentFactoryIndexOperationsOS(queryCache, clientProvider);
+ }
+
+ /** The factory with a real Elasticsearch leg and an OpenSearch leg missing its index. */
+ private static ESContentFactoryImpl factory() throws Exception {
+ return new ESContentFactoryImpl(
+ new ContentFactoryIndexOperationsES(CacheLocator.getESQueryCache()),
+ openSearchMissingIndex());
+ }
+
+ /**
+ * Method to test: {@link ContentFactoryIndexOperationsOS#indexCount(String)}
+ * Given Scenario: the OpenSearch provider is asked directly, with its index missing.
+ * Expected Result: it does NOT return the right count — it either throws or hands back its
+ * sentinel.
+ *
+ * This is the precondition the rest of the class depends on, and it asserts the failure
+ * is real rather than assuming it. Without it a green run could mean "the fallback works" or
+ * "nothing ever failed", and those must not be indistinguishable — the previous version of
+ * this class passed for exactly that reason while testing the wrong branch.
+ */
+ @Test
+ public void precondition_openSearchCannotServeTheQuery() throws Exception {
+ long osCount = Long.MIN_VALUE;
+ try {
+ osCount = openSearchMissingIndex().indexCount(query);
+ } catch (final Exception e) {
+ return; // throwing is one of the two acceptable outcomes
+ }
+ assertNotEquals("OpenSearch answered the query correctly, so the missing-index scenario "
+ + "is not being exercised and the rest of this class would pass vacuously",
+ 1L, osCount);
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexSearch(String, int, int, String)}
+ * Given Scenario: Phase 2, OpenSearch reachable but answering
+ * {@code index_not_found_exception}, Elasticsearch healthy and holding the
+ * content.
+ * Expected Result: the real Elasticsearch hits are served. Zero hits here is the silent
+ * variant of the outage — the dangerous one, because it is indistinguishable
+ * from an empty content type.
+ */
+ @Test
+ public void indexSearch_phase2_missingOsIndex_fallsBackToEs() throws Exception {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+
+ final SearchHits hits = factory().indexSearch(query, 10, 0, "modDate desc");
+
+ assertEquals("Phase 2 must serve the hits Elasticsearch holds when the OpenSearch "
+ + "counterpart index is missing", 1L, hits.getTotalHits().value());
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexCount(String)}
+ * Given Scenario: Phase 2, OpenSearch answering {@code index_not_found_exception}.
+ * Expected Result: the Elasticsearch count is served. A count of 0 is the silent variant;
+ * -1 is the sentinel leaking to the caller.
+ */
+ @Test
+ public void indexCount_phase2_missingOsIndex_fallsBackToEs() throws Exception {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+
+ final long count = factory().indexCount(query);
+
+ assertEquals("Phase 2 must serve the count Elasticsearch holds when the OpenSearch "
+ + "counterpart index is missing", 1L, count);
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexCount(String)}
+ * Given Scenario: Phase 3, OpenSearch answering {@code index_not_found_exception}.
+ * Elasticsearch is decommissioned in Phase 3.
+ * Expected Result: the caller must NOT receive Elasticsearch data. Either the sentinel or an
+ * exception is correct; silently serving Elasticsearch results would be a
+ * worse bug than the one being fixed, because it would report data absent
+ * from the only live engine.
+ */
+ @Test
+ public void indexCount_phase3_missingOsIndex_neverFallsBackToEs() throws Exception {
+ setPhase(MigrationPhase.PHASE_3_OPENSEARCH_ONLY);
+
+ long count = Long.MIN_VALUE;
+ try {
+ count = factory().indexCount(query);
+ } catch (final Exception e) {
+ return; // propagating is a correct Phase 3 outcome
+ }
+ assertNotEquals("Phase 3 must not fall back to Elasticsearch — it is decommissioned "
+ + "there, so serving its data would hide that OpenSearch has no index",
+ 1L, count);
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexSearch(String, int, int, String)}
+ * Given Scenario: Phase 3, OpenSearch answering {@code index_not_found_exception}.
+ * Expected Result: no Elasticsearch data, by the same reasoning as the count above.
+ */
+ @Test
+ public void indexSearch_phase3_missingOsIndex_neverFallsBackToEs() throws Exception {
+ setPhase(MigrationPhase.PHASE_3_OPENSEARCH_ONLY);
+
+ SearchHits hits = null;
+ try {
+ hits = factory().indexSearch(query, 10, 0, "modDate desc");
+ } catch (final Exception e) {
+ return; // propagating is a correct Phase 3 outcome
+ }
+ assertNotEquals("Phase 3 must not fall back to Elasticsearch",
+ 1L, hits.getTotalHits().value());
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexCount(String)}
+ * Given Scenario: Phase 1, where Elasticsearch serves reads and OpenSearch is a shadow.
+ * Expected Result: the count is correct and the missing OpenSearch index is irrelevant. The
+ * change must be a pure pass-through outside Phase 2 — these call sites
+ * carry essentially all content search, so any behaviour change here is
+ * felt site-wide in every phase.
+ */
+ @Test
+ public void indexCount_phase1_missingOsIndexIsIrrelevant() throws Exception {
+ setPhase(MigrationPhase.PHASE_1_DUAL_WRITE_ES_READS);
+
+ assertEquals("Phase 1 reads Elasticsearch regardless of OpenSearch index state",
+ 1L, factory().indexCount(query));
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexCount(String)}
+ * Given Scenario: Phase 0, the default.
+ * Expected Result: unchanged. Elasticsearch answers; the OpenSearch leg is never consulted.
+ */
+ @Test
+ public void indexCount_phase0_missingOsIndexIsIrrelevant() throws Exception {
+ setPhase(MigrationPhase.PHASE_0_MIGRATION_NOT_STARTED);
+
+ assertEquals("Phase 0 behaviour must be untouched",
+ 1L, factory().indexCount(query));
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexSearch(String, int, int, String)}
+ * Given Scenario: Phase 2, OpenSearch answering with an error, and the fallback firing.
+ * Expected Result: nothing is written to the OpenSearch query cache.
+ *
+ * This is the half of the query-cache concern that is a real defect rather than a
+ * reproduction hazard. The provider caches its error sentinel for some failure messages; on
+ * the Phase 2 path such an entry would be replayed to every later identical query as a
+ * successful empty result, outliving the outage and defeating the fallback even after
+ * OpenSearch recovers. The raise therefore has to happen before the cache write, and this
+ * asserts the order rather than trusting it.
+ *
+ * A cache hit during an outage is not a defect and is deliberately not tested
+ * here: the cached value is a real result from a real earlier query, so serving it is
+ * correct. It matters only because it hides the failure from a human running the
+ * reproduction — which cuts both ways, since it can just as easily produce a false
+ * confirmation that a fix works.
+ */
+ @Test
+ public void phase2_fallback_neverWritesTheErrorSentinelToTheQueryCache() throws Exception {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+ final OSQueryCache queryCache = mock(OSQueryCache.class);
+
+ final SearchHits hits = new ESContentFactoryImpl(
+ new ContentFactoryIndexOperationsES(CacheLocator.getESQueryCache()),
+ openSearchMissingIndex(queryCache))
+ .indexSearch(query, 10, 0, "modDate desc");
+
+ assertEquals("Precondition: the fallback must have served the Elasticsearch hits",
+ 1L, hits.getTotalHits().value());
+ verify(queryCache, never()).put(any(SearchRequest.class), any());
+ verify(queryCache, never()).put(any(CountRequest.class), any());
+ }
+}
diff --git a/dotcms-integration/src/test/java/com/dotcms/content/elasticsearch/business/ESContentFactoryImplPhase2FallbackTest.java b/dotcms-integration/src/test/java/com/dotcms/content/elasticsearch/business/ESContentFactoryImplPhase2FallbackTest.java
new file mode 100644
index 000000000000..b353dcccb92f
--- /dev/null
+++ b/dotcms-integration/src/test/java/com/dotcms/content/elasticsearch/business/ESContentFactoryImplPhase2FallbackTest.java
@@ -0,0 +1,218 @@
+package com.dotcms.content.elasticsearch.business;
+
+import static com.dotcms.content.index.IndexConfigHelper.MigrationPhase.FLAG_KEY;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import com.dotcms.content.index.ContentFactoryIndexOperations;
+import com.dotcms.content.index.IndexConfigHelper.MigrationPhase;
+import com.dotcms.content.index.IndexContentletScroll;
+import com.dotcms.content.index.domain.SearchHits;
+import com.dotcms.contenttype.model.type.ContentType;
+import com.dotcms.datagen.ContentTypeDataGen;
+import com.dotcms.datagen.ContentletDataGen;
+import com.dotcms.util.IntegrationTestInitService;
+import com.dotmarketing.business.CacheLocator;
+import com.dotmarketing.common.model.ContentletSearch;
+import com.dotmarketing.exception.DotRuntimeException;
+import com.dotmarketing.portlets.contentlet.model.Contentlet;
+import com.dotmarketing.portlets.contentlet.model.IndexPolicy;
+import com.dotmarketing.util.Config;
+import com.dotmarketing.util.PaginatedArrayList;
+import com.liferay.portal.model.User;
+import java.util.List;
+import org.junit.After;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+/**
+ * Integration tests proving that {@link ESContentFactoryImpl} routes its reads through
+ * {@link com.dotcms.content.index.PhaseRouter}, so the Phase 2 Elasticsearch fallback actually
+ * fires for content search (#37413).
+ *
+ * What regressed
+ * The fallback was implemented and correct; the content read path simply never reached it.
+ * {@code ESContentFactoryImpl} selected a provider with a bare ternary and called it directly
+ * from five read call sites, so the router was unreachable from the busiest read path in the
+ * product. In Phase 2 with OpenSearch down and Elasticsearch healthy and dual-written,
+ * {@code POST /api/content/_search} returned a well-formed {@code 200} with zero results — which
+ * a caller cannot tell apart from "this content type has no content", so a live site rendered as
+ * missing content with nothing for 5xx monitoring to catch.
+ *
+ * What this test adds over the unit tests
+ * {@code ContentFactoryIndexOperationsPhaseRoutingTest} pins the per-phase fallback contract
+ * against the provider interface, but a unit test on the router cannot show which class
+ * calls it — and that was the entire defect. This test is the wiring proof: it injects an
+ * OpenSearch provider that fails every read alongside the real Elasticsearch provider, and
+ * asserts that the factory's own read methods still return real Elasticsearch data. Before the
+ * fix these calls propagate the injected failure, because nothing catches it.
+ *
+ * @author Fabrizzio Araya
+ */
+public class ESContentFactoryImplPhase2FallbackTest {
+
+ private static ContentType contentType;
+ private static String query;
+
+ @BeforeClass
+ public static void prepare() throws Exception {
+ IntegrationTestInitService.getInstance().init();
+ contentType = new ContentTypeDataGen().nextPersisted();
+ // WAIT_FOR so the document is searchable before the assertions run.
+ final Contentlet contentlet = new ContentletDataGen(contentType.id())
+ .setPolicy(IndexPolicy.WAIT_FOR).nextPersistedAndPublish();
+ assertTrue("Test setup must produce a persisted contentlet",
+ null != contentlet.getInode());
+ query = "+contentType:" + contentType.variable() + " +live:true";
+ }
+
+ @After
+ public void clearPhase() {
+ Config.setProperty(FLAG_KEY, null);
+ }
+
+ private static void setPhase(final MigrationPhase phase) {
+ Config.setProperty(FLAG_KEY, String.valueOf(phase.ordinal()));
+ }
+
+ /**
+ * An OpenSearch provider standing in for an unreachable node: every read fails the way the
+ * real provider's generic handler wraps a connection failure.
+ */
+ private static final class UnreachableOpenSearch implements ContentFactoryIndexOperations {
+
+ private static DotRuntimeException down() {
+ return new DotRuntimeException("An error occurred when executing the Lucene Query",
+ new java.net.ConnectException("Connection refused"));
+ }
+
+ @Override
+ public String inferIndexToHit(final String query) {
+ throw down();
+ }
+
+ @Override
+ public long indexCount(final String query) {
+ throw down();
+ }
+
+ @Override
+ public SearchHits searchHits(final String query, final int limit, final int offset,
+ final String sortBy) {
+ throw down();
+ }
+
+ @Override
+ public List search(final String query, final int limit, final int offset) {
+ throw down();
+ }
+
+ @Override
+ public PaginatedArrayList indexSearchScroll(final String query,
+ final String sortBy, final int scrollBatchSize) {
+ throw down();
+ }
+
+ @Override
+ public IndexContentletScroll createScrollQuery(final String luceneQuery, final User user,
+ final boolean respectFrontendRoles, final int batchSize, final String sortBy) {
+ throw down();
+ }
+
+ @Override
+ public IndexContentletScroll createScrollQuery(final String luceneQuery, final User user,
+ final boolean respectFrontendRoles, final int batchSize) {
+ throw down();
+ }
+ }
+
+ /** A factory whose OpenSearch leg is dead and whose Elasticsearch leg is the real one. */
+ private static ESContentFactoryImpl factoryWithDeadOpenSearch() {
+ return new ESContentFactoryImpl(
+ new ContentFactoryIndexOperationsES(CacheLocator.getESQueryCache()),
+ new UnreachableOpenSearch());
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexCount(String)}
+ * Given Scenario: Phase 2, OpenSearch unreachable, Elasticsearch healthy and holding the
+ * content. This is the call that produced the 500s, because the count runs
+ * before the search and an uncached count threw.
+ * Expected Result: the real Elasticsearch count comes back — not 0, and not an exception.
+ */
+ @Test
+ public void indexCount_phase2_deadOpenSearch_servesElasticsearchCount() {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+
+ final long count = factoryWithDeadOpenSearch().indexCount(query);
+
+ assertEquals("Phase 2 must fall back to the count Elasticsearch holds", 1L, count);
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexSearch(String, int, int, String)}
+ * Given Scenario: Phase 2, OpenSearch unreachable, Elasticsearch healthy.
+ * Expected Result: the real hits come back. A zero-hit result here is the silent variant of
+ * the outage — the dangerous one, because it looks like an empty content
+ * type rather than a failure.
+ */
+ @Test
+ public void indexSearch_phase2_deadOpenSearch_servesElasticsearchHits() {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+
+ final SearchHits hits = factoryWithDeadOpenSearch()
+ .indexSearch(query, 10, 0, "modDate desc");
+
+ assertEquals("Phase 2 must fall back to the hits Elasticsearch holds",
+ 1L, hits.getTotalHits().value());
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexSearchScroll(String, String)}
+ * Given Scenario: Phase 2, OpenSearch unreachable, Elasticsearch healthy.
+ * Expected Result: the scroll is served from Elasticsearch. This site can fall back safely
+ * because it materialises the whole scroll before returning, so a failure
+ * leaves no cursor half-drained on the failing engine.
+ */
+ @Test
+ public void indexSearchScroll_phase2_deadOpenSearch_servesElasticsearchResults() {
+ setPhase(MigrationPhase.PHASE_2_DUAL_WRITE_OS_READS);
+
+ final PaginatedArrayList results =
+ factoryWithDeadOpenSearch().indexSearchScroll(query, "modDate desc");
+
+ assertEquals("Phase 2 must fall back to the scroll Elasticsearch can serve",
+ 1, results.size());
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexCount(String)}
+ * Given Scenario: Phase 1, where Elasticsearch serves reads and OpenSearch is only a shadow.
+ * Expected Result: the count is served without the dead OpenSearch provider being consulted
+ * at all. The routing change has to be a pure pass-through outside Phase 2 —
+ * these five call sites carry essentially all content search in the product,
+ * so any behaviour change here is felt site-wide in every phase.
+ */
+ @Test
+ public void indexCount_phase1_deadOpenSearchIsNeverConsulted() {
+ setPhase(MigrationPhase.PHASE_1_DUAL_WRITE_ES_READS);
+
+ final long count = factoryWithDeadOpenSearch().indexCount(query);
+
+ assertEquals("Phase 1 reads Elasticsearch and must not touch OpenSearch", 1L, count);
+ }
+
+ /**
+ * Method to test: {@link ESContentFactoryImpl#indexCount(String)}
+ * Given Scenario: Phase 0, the default — migration not started.
+ * Expected Result: same as Phase 1. Elasticsearch answers; OpenSearch is never contacted.
+ */
+ @Test
+ public void indexCount_phase0_deadOpenSearchIsNeverConsulted() {
+ setPhase(MigrationPhase.PHASE_0_MIGRATION_NOT_STARTED);
+
+ final long count = factoryWithDeadOpenSearch().indexCount(query);
+
+ assertEquals("Phase 0 reads Elasticsearch and must not touch OpenSearch", 1L, count);
+ }
+}
diff --git a/specs/37413-phase2-read-fallback/spec.md b/specs/37413-phase2-read-fallback/spec.md
new file mode 100644
index 000000000000..f66e50c141e5
--- /dev/null
+++ b/specs/37413-phase2-read-fallback/spec.md
@@ -0,0 +1,249 @@
+# Issue Resolution Specification: Phase 2 ES read fallback never fires for content search
+
+**Feature Branch**: `37413-phase2-read-fallback`
+
+**Created**: 2026-09-07
+
+**Status**: Draft
+
+**Type**: Issue / Bug Resolution
+
+**Related GitHub Issue**: #37413
+
+**Input**: User description: "37413"
+
+## Problem Statement *(mandatory)*
+
+The ES→OpenSearch migration design promises an automatic **read fallback to Elasticsearch in
+Phase 2**: OpenSearch serves reads, Elasticsearch is still live and in sync, and if OpenSearch
+throws on a read the error is logged at `ERROR` and the read is retried against Elasticsearch.
+That fallback is implemented, but the **content read path never reaches it**, so it never fires.
+
+With OpenSearch unavailable in Phase 2 and Elasticsearch up and holding a complete copy of the
+data, `POST /api/content/_search` does not fall back. It returns one of two things:
+
+- **HTTP 200 with `resultsSize: 0`** — a well-formed empty result. A caller cannot tell this
+ apart from "this content type has no content", so a live site renders as **missing content**
+ with no error surfaced anywhere and nothing for 5xx monitoring to catch.
+- **HTTP 500** — for content types whose count was not already cached.
+
+**Severity / Impact**: High. Every customer running Phase 2 loses the documented safety net —
+a transient OpenSearch blip, a slow node, or a missing OpenSearch index takes down content
+delivery instead of degrading to Elasticsearch. The silent-empty variant is the more dangerous
+of the two. Beyond the outage case, this also blocks recommending Phase 2 to customers at all:
+Cloud and Support are currently being told "Phase 2 is safe, OpenSearch failures fall back to
+Elasticsearch", and for content search that is false today.
+
+**This is not a regression.** With its read engine down dotCMS has always behaved this way —
+Phase 0 with Elasticsearch down does the same thing through the same legacy code. What is
+broken is the *promise*, not previously-working behavior. For content search the fallback
+wiring was never written.
+
+## Reproduction *(mandatory)*
+
+**Environment**: `main` @ `788795e915` (2026-09-03). Local instance in Phase 2
+(`DOT_FEATURE_FLAG_OPEN_SEARCH_PHASE=2`), Elasticsearch 7.10.2 and OpenSearch 3.4.0, real
+content indexed and in sync on both engines.
+
+**Steps to Reproduce**:
+
+1. Confirm the live phase from `GET /api/v1/jvm` (`DOT_FEATURE_FLAG_OPEN_SEARCH_PHASE` = `2`)
+ and that `GET /api/v1/index/migration/readiness` reports `readEngine: OpenSearch`.
+2. Stop the OpenSearch node (stop the container or block its port). Leave Elasticsearch running
+ and healthy.
+3. Call `POST /api/content/_search` for several content types that **do** have live content:
+ `{"query":"+contentType:Profile +live:true","limit":7,"offset":1}`
+4. **Vary `offset` on every call.** An identical request body is served from the query cache and
+ returns the pre-outage result, which looks exactly like a working fallback. Only novel,
+ uncached queries expose the defect — this is how it was nearly missed in QA.
+5. Observe the responses, then restart OpenSearch and repeat to confirm the content was present
+ the whole time.
+
+**Expected Behavior**: Every query returns the result set Elasticsearch holds, and each fallback
+is logged once at `ERROR` naming the failing OpenSearch operation and its cause.
+
+**Actual Behavior**:
+
+| Content type | Actual with OpenSearch down | Same call, OpenSearch up |
+|---|---|---|
+| Profile | **200, `total=0`** | 200, `total=184` |
+| Testimonials | **200, `total=0`** | 200, `total=317` |
+| JobPosting | **200, `total=0`** | 200, `total=27` |
+| Hero | **500** | 200, `total=215` |
+| ContactCard | **500** | 200, `total=106` |
+
+Failures are logged at **`WARN`**, not the `ERROR` the design specifies, so the "early-warning
+signal per read" is weaker than documented.
+
+**Reproducibility**: Always, on demand — provided the query is not already in the query cache
+(see step 4).
+
+## Scope of Investigation *(mandatory)*
+
+- **Affected area**: Content search / delivery read path (`/api/content/_search`, `ContentletAPI`
+ index reads, Velocity `$dotcontent.pull`), under the ES→OpenSearch migration phase routing.
+- **Suspected surface**: **Both.** The routing gap is in modern code
+ (`com.dotcms.content.elasticsearch.business.ESContentFactoryImpl`,
+ `com.dotcms.content.index.PhaseRouter`), but the reason the failure becomes an empty `200` is
+ legacy swallow behavior in `com.dotcms.rendering.velocity.viewtools.content.util.ContentUtils`
+ and `com.dotcms.rest.ContentHelper`.
+- **Related known decisions**: `docs/backend/OPENSEARCH_MIGRATION.md` lines 105, 402, 676 and 901
+ all state the Phase 2 read fallback as designed behavior — the document is the contract being
+ violated. Phase 3 must keep propagating read failures (no fallback; Elasticsearch is
+ decommissioned). The plan formally consults `dotCMS/platform-adrs`.
+
+## Root-Cause Hypothesis
+
+Two independent layers. Both were verified in the current tree.
+
+### Layer 1 — the router is never called (the actual defect)
+
+`ESContentFactoryImpl.java:273` picks an engine with a bare ternary and calls the chosen
+provider **directly**:
+
+```java
+ContentFactoryIndexOperations indexOperationsDelegate(){
+ return isMigrationComplete() || isReadEnabled() ? indexOperationsOS : indexOperationsES ;
+}
+```
+
+Its five read call sites — `:1352` `search`, `:1607` `indexCount`, `:1616` `searchHits`,
+`:1634` `indexSearchScroll`, `:1669` `createScrollQuery` — all invoke the selected provider with
+no router in between. `PhaseRouter.read` (`PhaseRouter.java:187-199`) and `readChecked`
+(`:298-310`) implement the fallback correctly and are simply unreachable from this path; the
+class contains no reference to `PhaseRouter` at all.
+
+The stack proves it by omission — no `PhaseRouter` frame between
+`ESContentFactoryImpl.indexCount` and `ContentFactoryIndexOperationsOS`. The same outage through
+`IndexAPIImpl` (the health check) *does* carry `PhaseRouter.read(PhaseRouter.java:192)`. Same
+failure, two paths, one routed.
+
+### Layer 2 — why the same outage yields 200/total=0 for some types and 500 for others
+
+> This supersedes the explanation in the GitHub issue body, which attributes the `200/total=0`
+> to the `OpenSearchException → ERROR_HIT` branch. That is **wrong** for the observed case: a
+> `ConnectException` is not an `OpenSearchException`, so it never reaches that branch. The
+> issue body needs correcting.
+
+1. `ContentHelper.pullContent:310` runs the **count first**. A `CountRequest` carries no
+ offset/limit, so varying the offset does not change the count cache key — content types
+ queried before the outage had a cached count and did not throw; types not previously queried
+ (Hero, ContactCard) missed the cache, the count threw, → **500**.
+2. `ContentUtils.java:302` has a `catch (Throwable)` that logs a one-line-truncated `WARN` and
+ returns an empty list, swallowing the search failure entirely.
+3. `ContentHelper.java:318` — `if (contentlets.isEmpty() && offset <= resultsSize) { resultsSize = 0; }`
+ overwrites the real cached count with `0` → **200 / `total=0`**.
+
+The `ERROR_HIT` branch (`ContentFactoryIndexOperationsOS.java:109-121`) is nonetheless a real
+second-order hazard: it converts an `OpenSearchException` into a legitimate-looking empty result,
+leaving the router nothing to catch. It is **inherited Elasticsearch behavior**, structurally
+identical in `ContentFactoryIndexOperationsES.java:56` and `:151-161` — so any change to it must
+be scoped carefully. Cache poisoning is bounded: `shouldQueryCache(exceptionMsg)` only caches
+`ERROR_HIT` for `parse_exception` / `search_phase_execution_exception`, so a connection failure
+is not cached.
+
+## Fix Scope & Non-Goals *(mandatory)*
+
+**In scope**:
+
+- Route the five read call sites of `ESContentFactoryImpl.indexOperationsDelegate()` through
+ `PhaseRouter.read` / `readChecked`, following the router pattern already documented in
+ `PhaseRouter`'s class Javadoc and used by `IndexAPIImpl`.
+- Ensure each Phase 2 fallback occurrence is logged at `ERROR` (the router already does this;
+ confirm no `WARN`-only path remains upstream of it).
+- Make the OpenSearch read path in Phase 2 surface a *throwable* failure to the router rather
+ than an empty result, for the failure classes the router is meant to catch — including a
+ missing OpenSearch counterpart index.
+- Tests: Phase 2 falls back and logs `ERROR`; Phase 3 propagates; the query cache does not mask
+ a live failure.
+
+**Explicitly out of scope / non-goals**:
+
+- **No change to Elasticsearch behavior.** `ContentFactoryIndexOperationsES` keeps its current
+ `ERROR_HIT` semantics; Phase 0 and Phase 1 read behavior is untouched.
+- **No fallback in Phase 3.** Failures must keep propagating there by design.
+- **No broad rewrite of the legacy swallow.** `ContentUtils.java:302`'s `catch (Throwable)` and
+ `ContentHelper.java:318`'s `resultsSize = 0` overwrite are pre-existing and affect all phases,
+ including pure Elasticsearch. They explain the *symptom*, and fixing Layer 1 removes the
+ Phase 2 case. Changing them repo-wide is a separate, larger issue — file it, do not fold it in.
+- **No `IndexAPI` generic parameterization** — that belongs in its own PR.
+- No write-path changes. Write failure semantics per phase are settled elsewhere.
+- No new configuration property or feature flag to switch the fallback on and off — it is
+ documented, unconditional Phase 2 behavior.
+
+## Regression Risk *(mandatory)*
+
+- **Blast radius**: `ESContentFactoryImpl`'s five read call sites are the funnel for essentially
+ all content search — `/api/content/_search`, `ContentletAPI.search`/`searchIndex`/`indexCount`,
+ Velocity `$dotcontent.pull`, URL maps, Site Search, scroll/pagination consumers, and the
+ admin UI content browser. Any behavior change here is felt site-wide in every phase, so the
+ routing change must be a pure pass-through in phases 0, 1 and 3.
+- **Callers that depend on empty-instead-of-exception**: making the OpenSearch read throw where
+ it currently returns `ERROR_HIT` changes the contract for anything that today receives an
+ empty result. These callers must be enumerated before that change lands, and each confirmed
+ either unaffected or explicitly handled. If the enumeration turns out to be large, the routing
+ fix (Layer 1) still stands on its own and can ship without touching `ERROR_HIT`.
+- **Scroll and pagination**: `indexSearchScroll` and `createScrollQuery` hold engine-specific
+ cursor state. A mid-scroll fallback cannot resume an OpenSearch scroll on Elasticsearch — the
+ plan must decide whether these two sites fall back at all or only propagate, and say so.
+- **Backward compatibility**: no API contract, response shape, serialized state, DB schema or
+ index mapping changes. Not rollback-unsafe.
+- **Data considerations**: none — no data repair needed. Content missing from a read during an
+ outage was never lost; it is in Elasticsearch the whole time.
+- **Performance**: a fallback doubles the work for a failing read. Bounded to the outage window,
+ and the failing engine fails fast, but the plan should confirm no retry storm (one fallback
+ attempt per read, no nesting).
+
+## Acceptance & Verification *(mandatory)*
+
+- **AC-001**: The reproduction above produces the expected behavior — in Phase 2 with
+ OpenSearch stopped and Elasticsearch healthy, `POST /api/content/_search` returns the same
+ non-zero result set Elasticsearch holds for **every** content type that has live content. No
+ `total=0`, no 500.
+- **AC-002**: All five read call sites of `indexOperationsDelegate()` (`:1352`, `:1607`, `:1616`,
+ `:1634`, `:1669`) go through `PhaseRouter.read` / `readChecked` instead of invoking the
+ selected provider directly — or, for a site the plan excludes (see scroll/pagination above),
+ the exclusion is documented in code with its reason.
+- **AC-003**: Each fallback occurrence is logged at `ERROR`, once per read, naming the failing
+ OpenSearch operation and the cause — so an outage is visible to log-based monitoring per the
+ design's early-warning signal. No `WARN`-only swallow remains on the Phase 2 fallback path.
+- **AC-004**: Phase 0, 1 and 3 read behavior is byte-for-byte unchanged: 0/1 read from
+ Elasticsearch with no fallback; 3 reads from OpenSearch and propagates failures. Verified by
+ test, not by inspection.
+- **AC-005**: A missing OpenSearch counterpart index in Phase 2 is served from Elasticsearch
+ rather than returning empty, matching `OPENSEARCH_MIGRATION.md:402` — this also covers the
+ reactivated-backup-index scenario.
+- **AC-006**: If the `OpenSearchException`/`ERROR_HIT` branch is changed, Elasticsearch's
+ equivalent branch (`ContentFactoryIndexOperationsES.java:151-161`) is **not** changed, Phase 3
+ still propagates, and the enumeration of callers relying on the empty result is recorded in
+ the plan with each one confirmed unaffected.
+- **AC-007**: A repeated identical query does not mask a live OpenSearch failure by serving a
+ stale pre-outage result from the query cache — the caller either gets fallback results or a
+ surfaced error, never a silent stale hit presented as current.
+
+**Verification method**:
+
+- Integration test — Phase 2 with the OpenSearch provider stubbed to throw: a content search
+ returns the Elasticsearch result set and logs at `ERROR`.
+- Integration test — the same stubbed failure in Phase 3 propagates and does **not** fall back.
+- Integration test — phases 0/1 unchanged (AC-004).
+- Integration test — the query-cache path (AC-007).
+- All of the above live in `dotcms-integration`, are named `*Test` (not `*IT`), and are
+ **registered in the matching `@SuiteClasses` suite** — an unregistered class compiles, passes
+ CI green, and never runs.
+- Run: `./mvnw verify -pl :dotcms-integration -Dcoreit.test.skip=false -Dit.test=`
+ (requires the WAR to be installed first, not just compiled).
+- Manual re-run of the reproduction on the Phase 2 real-data rig, varying `offset` per call.
+
+## Assumptions
+
+- The intended behavior is what `docs/backend/OPENSEARCH_MIGRATION.md` states; no ADR overrides
+ it. The plan will confirm against `dotCMS/platform-adrs`.
+- Elasticsearch being in sync in Phase 2 is a given — Phase 2 is dual-write, so ES is
+ continuously written. A fallback returning stale-but-present ES data is strictly better than
+ returning nothing.
+- The scroll/pagination question (AC-002 exclusion) is a plan-phase decision, not a
+ specification gap: either answer satisfies the design as long as it is deliberate and
+ documented.
+- The GitHub issue body will be corrected to match Layer 2 above before implementation, so the
+ issue and this spec do not disagree on root cause.