feat(seat): CP stdio seat arm chain on the folded 5.17.0 basis (hook-series chain + set-streaming arm + contract-tests/seat decoupling)

.gitignore

@@ -12,3 +12,13 @@ build
 .project
 .settings/
 .vscode/
+
+# CENTINEL seat lane (local branches; never pushed upstream): build outputs and probe leftovers
+/gen/
+/sdk-classes/
+/seat-classes/
+/sdk.jar
+tools/seat-test/classes/
+tools/seat-test/extracted-cons/
+tools/seat-test/stub-src/
+tools/seat-test/stub-src-tmp/

README.md

@@ -40,3 +40,10 @@ We encourage pull requests and other contributions from the community. Check out
     * [docs.launchdarkly.com](https://docs.launchdarkly.com/  "LaunchDarkly Documentation") for our documentation and SDK reference guides
     * [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/  "LaunchDarkly API Documentation") for our API documentation
     * [launchdarkly.com/blog](https://launchdarkly.com/blog/  "LaunchDarkly Blog Documentation") for the latest product updates
+
+## Continuous integration
+
+`docs/ci/contract-tests.yml.template` holds the CI gate's bytes: an operator applies
+them at `.github/workflows/contract-tests.yml`, and the landed workflow prices the
+`ConnectivityManagerTest` replay faces — the `a243c235` FDv2-OFFLINE double-window
+trio — on every pull request to `main` (Ubuntu Actions runner, ubuntu-22.04, JDK 17).

contract-tests/src/main/java/com/launchdarkly/sdk/android/ConfigHelper.java

@@ -1,10 +1,86 @@
 package com.launchdarkly.sdk.android;
 
+import com.launchdarkly.sdk.LDContext;
+
+import java.util.concurrent.ConcurrentHashMap;
+
 public class ConfigHelper {
     // This method exists because Config.Builder.persistentDataStore is currently package-private -
     // using a custom persistence component is not yet part of the public API.
     public static LDConfig.Builder configureIsolatedInMemoryPersistence(LDConfig.Builder builder) {
         builder.persistentDataStore(new InMemoryPersistentDataStore());
         return builder;
     }
+
+    /**
+     * CENTINEL client-lane extension (campaign client-INTERFACE section 5, PERSIST.5):
+     * with a storage scope every client created under the same scope tag shares one local
+     * store (successive launches of one app); without one each client stays isolated as
+     * before. Returns the store wired into the builder so the caller can preload data.
+     */
+    private static final ConcurrentHashMap<String, InMemoryPersistentDataStore> SCOPED_STORES =
+            new ConcurrentHashMap<String, InMemoryPersistentDataStore>();
+
+    public static InMemoryPersistentDataStore configureInMemoryPersistence(LDConfig.Builder builder,
+            String storageScope) {
+        InMemoryPersistentDataStore store = storageScope == null
+                ? new InMemoryPersistentDataStore()
+                : SCOPED_STORES.computeIfAbsent(storageScope, k -> new InMemoryPersistentDataStore());
+        builder.persistentDataStore(store);
+        return store;
+    }
+
+    /**
+     * CENTINEL client-lane extension: writes bootstrap flag data (the campaign's
+     * x-cp-bootstrap all-flags-state JSON) through the SDK's own persisted-store
+     * pathway, so the real {@code FDv2CacheInitializer} serves the values during
+     * client initialization — exactly the LD offline-cache bootstrapping contract.
+     *
+     * The all-flags-state shape carries values at the top level with per-flag
+     * metadata under {@code $flagsState}; the store format is the flat
+     * {@code {flagKey: Flag}} map, so the conversion keeps key/value/version/variation.
+     */
+    public static void preloadBootstrapData(InMemoryPersistentDataStore store,
+            String mobileKey, java.util.Map<String, Object> bootData, LDContext initialContext) {
+        if (store == null || bootData == null || initialContext == null) {
+            return;
+        }
+        // Mirrors PersistentDataStoreWrapper's own namespacing: the per-environment
+        // namespace hashes the mobile key; the per-context key hashes the context's
+        // fully-qualified key. The literal prefixes live in the wrapper (private); the
+        // SDK's hash helpers are package-visible to this same-package caller.
+        String namespace = "LaunchDarkly_" + LDUtil.urlSafeBase64Hash(mobileKey == null ? "" : mobileKey);
+        String key = "flags_" + LDUtil.urlSafeBase64HashedContextId(initialContext);
+
+        com.google.gson.Gson gson = new com.google.gson.Gson();
+        com.google.gson.JsonObject flags = new com.google.gson.JsonObject();
+        Object stateRaw = bootData.get("$flagsState");
+        java.util.Map<?, ?> flagsState = stateRaw instanceof java.util.Map ? (java.util.Map<?, ?>) stateRaw : null;
+        for (java.util.Map.Entry<String, Object> e : bootData.entrySet()) {
+            String flagKey = e.getKey();
+            if (flagKey.startsWith("$")) {
+                continue; // $flagsState / $valid metadata
+            }
+            com.google.gson.JsonObject f = new com.google.gson.JsonObject();
+            f.addProperty("key", flagKey);
+            f.add("value", gson.toJsonTree(e.getValue()));
+            int version = 1;
+            Integer variation = null;
+            if (flagsState != null && flagsState.get(flagKey) instanceof java.util.Map<?, ?>) {
+                java.util.Map<?, ?> fs = (java.util.Map<?, ?>) flagsState.get(flagKey);
+                if (fs.get("version") instanceof Number) {
+                    version = ((Number) fs.get("version")).intValue();
+                }
+                if (fs.get("variation") instanceof Number) {
+                    variation = ((Number) fs.get("variation")).intValue();
+                }
+            }
+            f.addProperty("version", version);
+            if (variation != null) {
+                f.addProperty("variation", variation);
+            }
+            flags.add(flagKey, f);
+        }
+        store.setValue(namespace, key, gson.toJson(flags));
+    }
 }

contract-tests/src/main/java/com/launchdarkly/sdktest/HookCallbackService.java

@@ -15,6 +15,15 @@ public HookCallbackService(URI serviceUri) {
     }
 
     public void post(Object params) {
+        // CENTINEL seat extension (CP-SPEC 7.2): a cp-callback:// callback URI rides
+        // the CP/stdio callback wheel — the seat MUST NOT dial it; it emits a
+        // `callback` envelope and awaits the runner's reply on stdin before the
+        // SDK-side call completes. Any other scheme keeps the harness's own
+        // HTTP receiver arm (used when the seat runs under CP/http on a device).
+        if (serviceUri != null && "cp-callback".equals(serviceUri.getScheme())) {
+            SdkClientEntity.seatPostCallbackHTTPFace(serviceUri, params);
+            return;
+        }
         RequestBody body = RequestBody.create(
             TestService.gson.toJson(params == null ? "{}" : params),
             MediaType.parse("application/json")

contract-tests/src/main/java/com/launchdarkly/sdktest/Representations.java

@@ -40,6 +40,7 @@ public static class SdkConfigParams {
         SdkConfigServiceEndpointParams serviceEndpoints;
         SdkConfigHookParams hooks;
         SdkConfigDataSystemParams dataSystem;
+        SdkConfigWrapperParams wrapper;
     }
 
     public static class SdkConfigStreamParams {
@@ -74,11 +75,25 @@ public static class SdkConfigServiceEndpointParams {
         String events;
     }
 
+    /** cp.schema sdkConfiguration/properties/wrapper (v3:L384): the
+     * X-LaunchDarkly-Wrapper header config. Declared under the
+     * `wrapper` capability. */
+    public static class SdkConfigWrapperParams {
+        String name;
+        String version;
+    }
+
     public static class SdkConfigClientSideParams {
         LDContext initialContext;
         boolean evaluationReasons;
         boolean useReport;
         boolean includeEnvironmentAttributes;
+
+        // CENTINEL seat extensions (campaign client-INTERFACE section 5): a blind storage
+        // scope tag whose clients share one local store (PERSIST.5), and bootstrap flag
+        // data in the all-flags-state shape for the SDK's pre-connection serve.
+        @SerializedName("x-cp-storage-scope") String xCpStorageScope;
+        @SerializedName("x-cp-bootstrap") java.util.Map<String, Object> xCpBootstrap;
     }
 
     public static class SdkConfigHookParams {
@@ -95,6 +110,9 @@ public static class HookConfig {
     public static class HookData {
         Map<String, Object> beforeEvaluation;
         Map<String, Object> afterEvaluation;
+        Map<String, Object> afterTrack;
+        Map<String, Object> beforeIdentify;
+        Map<String, Object> afterIdentify;
     }
 
     public static class HookErrors {
@@ -137,6 +155,52 @@ public static class CommandParams {
         CustomEventParams customEvent;
         ContextBuildParams contextBuild;
         ContextConvertParams contextConvert;
+        RegisterFlagChangeListenerParams registerFlagChangeListener;
+        UnregisterListenerParams unregisterListener;
+        ContextComparisonParams contextComparison;
+        @com.google.gson.annotations.SerializedName("x-cp-create-no-credential") XcpCreateNoCredentialParams xcpCreateNoCredential;
+        SetOverrideParams setOverride;
+        RemoveOverrideParams removeOverride;
+        @com.google.gson.annotations.SerializedName("x-cp-closed-evaluate") EvaluateFlagParams xcpClosedEvaluate;
+        @com.google.gson.annotations.SerializedName("x-cp-set-streaming") SetStreamingParams xcpSetStreaming;
+    }
+
+    /** x-cp-set-streaming arm params (cp.schema x-cp-set-streaming: `state`
+     * boolean|null — true forces streaming, false forces polling, null resets
+     * the SDK's automatic mode resolution). */
+    public static class SetStreamingParams {
+        Boolean state;
+    }
+
+    public static class SetOverrideParams {
+        String flagKey;
+        LDValue value;
+    }
+
+    public static class RemoveOverrideParams {
+        String flagKey;
+    }
+
+    /** x-cp-create-no-credential request arm (the harness's own x-cp face). */
+    public static class XcpCreateNoCredentialParams {
+        LDContext initialContext;
+    }
+
+    /** The context-comparison response (spec): `equals` prices the SDK's own
+     * LDContext equality (kind+key+attrs). */
+    public static class ContextComparisonResponse {
+        Boolean equals;
+    }
+
+    /** service_spec listener command params (L706/L754): the seat echoes
+     * listenerId in every notification for the listener. */
+    public static class RegisterFlagChangeListenerParams {
+        String listenerId;
+        URI callbackUri;
+    }
+
+    public static class UnregisterListenerParams {
+        String listenerId;
     }
 
     public static class EvaluateFlagParams {
@@ -169,10 +233,18 @@ public static class EvaluationSeriesCallbackParams {
         String stage;
     }
 
+    /** The identify hook series' callback payload (spec HOOK 1.4.x). */
+    public static class IdentifySeriesCallbackParams {
+        public com.launchdarkly.sdk.android.integrations.IdentifySeriesContext identifySeriesContext;
+        public Map<String, Object> identifySeriesData;
+        public com.launchdarkly.sdk.android.integrations.IdentifySeriesResult identifyResult;
+        public String stage;
+    }
+
     public static class TrackSeriesCallbackParams {
+        public Map<String, Object> evaluationSeriesData;
         TrackSeriesContext trackSeriesContext;
-        String stage;
-    }
+        String stage;    }
 
     public static class IdentifyEventParams {
         LDContext context;
@@ -205,6 +277,11 @@ public static class ContextBuildResponse {
         String error;
     }
 
+    public static class ContextComparisonParams {
+        ContextBuildParams context1;
+        ContextBuildParams context2;
+    }
+
     public static class ContextConvertParams {
         String input;
     }