fix: align experimentation with new ExP contract

Use the approved assignments endpoint and reserve DevDeviceId as the platform-owned identity while keeping live requests disabled until VS Code exposes an approved provider.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: StellaHuang95

CONTRIBUTING.md

@@ -85,9 +85,10 @@ Run unit tests with the different configurations in the "Run and Debug" panel
 
 See [Experimentation infrastructure](./docs/experimentation.md) for the internal TAS
 service, publisher configuration, lifecycle and consent behavior, deterministic tests,
-and the baseline measurement inventory. Live experimentation remains unconfigured until
-the endpoint and identity contract have been approved; this infrastructure does not
-enable a feature or publish an experimental setting.
+and the baseline measurement inventory. The new assignments endpoint is fixed by the
+platform, but live experimentation remains unconfigured until VS Code exposes an approved
+DevDeviceId provider. This infrastructure does not enable a feature or publish an
+experimental setting.
 
 ## Contributor License Agreement (CLA)
 

docs/experimentation.md

@@ -2,27 +2,39 @@
 
 The extension owns one internal TAS service per activation. This infrastructure
 supports general experimentation and measurement without enabling product features.
-Live TAS configuration remains absent until the platform owners approve the endpoint
-and identity contract.
+The new assignments endpoint and parameter name are platform-owned. Live TAS
+configuration remains absent until VS Code provides an approved DevDeviceId API to
+the extension.
+
+## Settings rollout versus extension attribution
+
+An `onExP` settings rollout does not require this service merely to apply its
+treatment. Declare the setting with a safe package default and the `onExP` tag,
+configure `config.<full-setting-id>` in ExP, and read the effective value through
+`workspace.getConfiguration()`. VS Code core retrieves the assignment and applies
+the treatment as a default; explicit user and workspace values still take
+precedence. Do not add a second TAS treatment gate for the same setting.
+
+Use this service when an extension-owned experiment needs treatment variables, or
+when Python Environments telemetry must carry the matching assignment context for
+an experiment scorecard.
 
 ## Publisher configuration
 
 `initializeExperimentation()` reads an optional top-level `experimentation` object
 from the installed extension's `package.json`. This is publisher-owned metadata,
-**not** a VS Code setting: a workspace must not be able to redirect requests that
-contain an identifier.
+**not** a VS Code setting. The endpoint and identity parameter cannot be overridden
+by publisher or workspace configuration.
 
-The following is a schema illustration, not deployable configuration. Replace the
-placeholders only with reviewed values; do not copy names from legacy `X-*` headers.
+The following is a schema illustration, not deployable configuration. The manifest
+entry must remain absent until the DevDeviceId provider is approved and wired.
+Do not copy names from legacy `X-*` headers.
 
 ```json
 {
     "experimentation": {
-        "assignmentsEndpoint": "https://<approved-host>/api/v1/assignments",
         "targetPopulation": "public",
-        "identityParameter": "<approved-identity-parameter>",
         "assignmentParameters": {
-            "<approved-identity-parameter>": "machineId",
             "<approved-extension-version-parameter>": "extensionVersion",
             "<approved-language-parameter>": "language"
         }
@@ -33,19 +45,30 @@ placeholders only with reviewed values; do not copy names from legacy `X-*` head
 Supported populations are `public`, `insider`, `internal`, and `team`. Select one
 explicitly with the owners; an `internal` value is not authentication or proof of
 employee status. Version and language bindings are optional. The identity binding
-is mandatory and must occur exactly once. Generic SDK parameters cannot be overridden.
+`"devdeviceid": "devDeviceId"` is added by the platform configuration and cannot be
+overridden. Generic SDK parameters cannot be overridden.
+
+The approved full endpoint is:
+
+```text
+https://exp.individual.githubcopilot.com/api/v1/assignments
+```
+
+The host is currently fixed rather than taken from a Copilot token. Business and
+Enterprise networks may block the Individual endpoint; those failures must remain
+nonfatal and their telemetry unattributed. Validate attribution coverage before
+using extension events in a scorecard.
 
-The currently implemented identity source is VS Code's public `env.machineId` API.
-It must only be used when that is the approved randomization identity. **MachineId
-is not DevDeviceId.** If onboarding requires DevDeviceId or another identity, add and
-review its provider first; unsupported sources are rejected, not silently substituted.
-Ensure the analysis identity, and any future VS Code core setting experiment's
-identity, agrees with this contract.
+The public extension API does not currently expose DevDeviceId. The service accepts
+an injected provider so the approved API can be connected without falling back to
+MachineId. Until that provider is available, configured initialization fails closed
+and makes no TAS request. The legacy MachineId read elsewhere in the service only
+namespaces cache data for the SDK's inherited legacy request; it is not the new
+assignments identity.
 
 Absent configuration reports `notConfigured` and makes no TAS requests. Invalid
 configuration reports an error and also makes no requests; it does not silently
-fall back to a legacy-only integration. No endpoint, identity value, or mapping is
-accepted from workspace configuration.
+fall back to a legacy-only integration.
 
 ## Service lifecycle and queries
 
@@ -82,10 +105,11 @@ snapshot queries, not refresh requests.
 
 Cache data lives in `context.globalState`, namespaced by the approved configuration,
 extension version, resolved assignment parameters, and the SDK's built-in targeting
-values: VS Code version, application name, language, and legacy MachineId. The namespace
-is hashed; identifiers and endpoints are not emitted in diagnostics. This prevents a
-snapshot from being reused after its population, endpoint, version, identity, or audience
-context changes. Malformed cache data is ignored with a warning.
+values: VS Code version, application name, language, and legacy MachineId. The new
+assignments identity is DevDeviceId. The namespace is hashed; identifiers and
+endpoints are not emitted in diagnostics. This prevents a snapshot from being reused
+after its population, endpoint, version, identity, or audience context changes.
+Malformed cache data is ignored with a warning.
 
 Revoking telemetry consent disposes the SDK, aborts outstanding requests, clears
 shared attribution, and makes queries use defaults. Re-enabling consent creates a
@@ -98,7 +122,9 @@ New-endpoint variables take precedence when both return the same name. The commo
 HTTPS transport supplies cancellation, a ten-second request deadline, and a two-MiB
 response cap to both endpoints. It uses Node HTTPS like the SDK, retaining the
 extension host's HTTP hooks; proxy behavior must still be verified in the deployment
-environments. There is no insecure TLS or redirect fallback.
+environments. There is no insecure TLS or redirect fallback. New experiments must
+use the shared GitHub/DevDiv workspace and the assignments POST; the inherited
+legacy request is SDK behavior and is not a supported fallback for this extension.
 
 `tas-client` requires Node 22. TypeScript 5.8 or newer is needed to type-check the
 current wrapper's CommonJS-to-ESM declarations without disabling library checking.
@@ -177,13 +203,15 @@ Unit tests use a fake SDK for lifecycle cases. A separate contract test loads th
 installed SDK with a fake transport to verify dual requests, assignment merging,
 bare variable names, and shared attribution without contacting TAS.
 
-Before live use, confirm the endpoint, identity names/source, audience/population,
-ExP workspace, access, and scorecard with the VS Code experimentation owners. Obtain the integration and
-metrics reviews described in the onboarding guidance. An A/A can validate allocation,
-attribution, data quality and baseline stability without exposing a new setting or
-changing product behavior. A real `tas-call` with `callType = assignments` and
-`outcome = Success`, a known new-endpoint assignment, and tagged subsequent telemetry
-must all agree; a cached value alone is not proof that onboarding works.
+Before live use, obtain DevDeviceId access and confirm the audience/population, shared
+GitHub/DevDiv workspace group, access, and scorecard with the experimentation owners.
+The old workspace and old TAS endpoint are not supported for new experiments. Obtain
+the integration and metrics reviews described in the onboarding guidance. An A/A can
+validate allocation, attribution, data quality and baseline stability without exposing
+a new setting or changing product behavior. A real `tas-call` with
+`callType = assignments` and `outcome = Success`, a known new-endpoint assignment,
+and tagged subsequent telemetry must all agree; a cached value alone is not proof
+that onboarding works.
 
 Some older checklists still require `vscode.abexp.features`; the current SDK no
 longer maintains it. Use the current assignment-context guidance instead. The

src/common/env.apis.ts

@@ -19,7 +19,7 @@ export function onDidChangeTelemetryEnabled(listener: (enabled: boolean) => void
     return env.onDidChangeTelemetryEnabled(listener);
 }
 
-/** Read the machine identifier for an approved identity binding. */
+/** Read the legacy MachineId targeting value that vscode-tas-client adds automatically. */
 export function getMachineId(): string {
     return env.machineId;
 }

src/common/experimentation/configuration.ts

@@ -2,7 +2,11 @@
 // Licensed under the MIT License.
 
 export type ExperimentationPopulation = 'public' | 'insider' | 'internal' | 'team';
-export type AssignmentParameterSource = 'machineId' | 'extensionVersion' | 'language';
+export type AssignmentParameterSource = 'devDeviceId' | 'extensionVersion' | 'language';
+
+export const EXPERIMENTATION_ASSIGNMENTS_ENDPOINT =
+    'https://exp.individual.githubcopilot.com/api/v1/assignments';
+export const EXPERIMENTATION_IDENTITY_PARAMETER = 'devdeviceid';
 
 export interface ExperimentationConfiguration {
     readonly assignmentsEndpoint: string;
@@ -12,6 +16,7 @@ export interface ExperimentationConfiguration {
 }
 
 const GENERIC_PARAMETERS = new Set([
+    EXPERIMENTATION_IDENTITY_PARAMETER,
     'vscode_core_appversion',
     'vscode_core_build',
     'vscode_core_extensionname',
@@ -32,61 +37,43 @@ export function readExperimentationConfiguration(manifest: unknown): Experimenta
     if (!isRecord(config)) {
         throw new Error('The experimentation manifest entry must be an object.');
     }
-    const endpoint = config.assignmentsEndpoint;
-    if (typeof endpoint !== 'string') {
-        throw new Error('Experimentation requires an approved assignmentsEndpoint.');
-    }
-    const url = new URL(endpoint);
-    if (
-        url.protocol !== 'https:' ||
-        url.username ||
-        url.password ||
-        url.search ||
-        url.hash ||
-        !url.pathname.endsWith('/api/v1/assignments')
-    ) {
+    if (config.assignmentsEndpoint !== undefined || config.identityParameter !== undefined) {
         throw new Error(
-            'assignmentsEndpoint must be an HTTPS assignments API URL without credentials or query parameters.',
+            'The experimentation endpoint and identity parameter are platform-owned and cannot be overridden.',
         );
     }
     const population = config.targetPopulation;
     if (population !== 'public' && population !== 'insider' && population !== 'internal' && population !== 'team') {
         throw new Error('Experimentation requires an explicitly approved targetPopulation.');
     }
-    if (!isRecord(config.assignmentParameters)) {
+    if (config.assignmentParameters !== undefined && !isRecord(config.assignmentParameters)) {
         throw new Error('Experimentation requires approved assignment parameter bindings.');
     }
 
-    const parameters: Record<string, AssignmentParameterSource> = {};
-    for (const [name, source] of Object.entries(config.assignmentParameters)) {
+    const parameters: Record<string, AssignmentParameterSource> = {
+        [EXPERIMENTATION_IDENTITY_PARAMETER]: 'devDeviceId',
+    };
+    for (const [name, source] of Object.entries(config.assignmentParameters ?? {})) {
         if (!/^[A-Za-z][A-Za-z0-9_.-]*$/.test(name) || /^x-/i.test(name) || GENERIC_PARAMETERS.has(name)) {
             throw new Error(
                 'Assignment parameters must use new API names and must not replace generic SDK parameters.',
             );
         }
-        if (source !== 'machineId' && source !== 'extensionVersion' && source !== 'language') {
+        if (source !== 'extensionVersion' && source !== 'language') {
             throw new Error(
-                'Unsupported assignment parameter source. Add an approved identity provider before enabling TAS.',
+                'Unsupported assignment parameter source. The DevDeviceId binding is platform-owned.',
             );
         }
         parameters[name] = source;
     }
-    const identityParameter = config.identityParameter;
-    if (
-        typeof identityParameter !== 'string' ||
-        parameters[identityParameter] !== 'machineId' ||
-        Object.values(parameters).filter((source) => source === 'machineId').length !== 1 ||
-        Object.keys(parameters).length > 45
-    ) {
-        throw new Error(
-            'Experimentation requires one explicitly approved machineId identity binding and at most 45 parameters.',
-        );
+    if (Object.keys(parameters).length > 45) {
+        throw new Error('Experimentation supports at most 45 assignment parameters.');
     }
 
     return {
-        assignmentsEndpoint: url.toString(),
+        assignmentsEndpoint: EXPERIMENTATION_ASSIGNMENTS_ENDPOINT,
         targetPopulation: population,
-        identityParameter,
+        identityParameter: EXPERIMENTATION_IDENTITY_PARAMETER,
         assignmentParameters: Object.freeze(parameters),
     };
 }

src/common/experimentation/service.ts

@@ -45,6 +45,7 @@ export type ExperimentationClientOptions = Omit<ExperimentationConfig, 'targetPo
 export type ExperimentationClientFactory = (
     options: ExperimentationClientOptions,
 ) => ExperimentationClient | Promise<ExperimentationClient>;
+export type DevDeviceIdProvider = () => string | undefined;
 
 export interface ExperimentationContext {
     readonly extension: { readonly packageJSON: unknown };
@@ -106,6 +107,7 @@ export class ExperimentationService implements Disposable {
     constructor(
         private readonly context: ExperimentationContext,
         private readonly createClient: ExperimentationClientFactory = createSdk,
+        private readonly getDevDeviceId: DevDeviceIdProvider = () => undefined,
         disabledForTests = false,
     ) {
         try {
@@ -241,12 +243,12 @@ export class ExperimentationService implements Disposable {
 
     private async initialize(run: SdkRun): Promise<void> {
         const configuration = this.configuration!;
-        const identity = getMachineId();
+        const identity = this.getDevDeviceId();
         if (typeof identity !== 'string' || !identity.trim()) {
-            throw new Error('The configured experimentation identity is unavailable.');
+            throw new Error('The approved DevDeviceId experimentation identity is unavailable.');
         }
         const language = getLanguage();
-        const values = { machineId: identity, extensionVersion: this.version, language };
+        const values = { devDeviceId: identity, extensionVersion: this.version, language };
         const parameters = new Map<string, string>();
         for (const [name, source] of Object.entries(configuration.assignmentParameters)) {
             const value = values[source];
@@ -259,7 +261,7 @@ export class ExperimentationService implements Disposable {
         const sdkTargetingValues = {
             applicationVersion: trimVersionSuffix(getVSCodeVersion()),
             build: getAppName(),
-            clientId: identity,
+            clientId: getMachineId(),
             language,
         };
         const storage = new ExperimentationStorage(
@@ -422,14 +424,15 @@ let activeService: ExperimentationService | undefined;
 /** Register the activation's internal service without awaiting networking. */
 export function initializeExperimentation(
     context: ExperimentationContext & { subscriptions: Disposable[] },
+    getDevDeviceId?: DevDeviceIdProvider,
 ): ExperimentationService {
     if (activeService) {
         return activeService;
     }
     const testExecution = [
         'VSC_PYTHON_CI_TEST', 'VSC_PYTHON_INTEGRATION_TEST', 'VSC_PYTHON_SMOKE_TEST', 'VSC_PYTHON_E2E_TEST',
     ].some((name) => !!process.env[name]);
-    const service = new ExperimentationService(context, createSdk, testExecution);
+    const service = new ExperimentationService(context, createSdk, getDevDeviceId, testExecution);
     activeService = service;
     context.subscriptions.push({
         dispose: () => {