refactor: replace specVersions list with introducedIn/removedIn range tagging

Replaces per-scenario `specVersions: SpecVersion[]` arrays with `introducedIn`
and optional `removedIn` range fields on all three scenario interfaces. Extension
scenarios get an orthogonal `extension?: boolean` flag instead of the former
`'extension'` tag in the versions list.

matchesSpecVersion() is rewritten as a range comparison
(introducedIn <= target && (!removedIn || target < removedIn)), with draft
sorting after all dated versions. getScenarioSpecVersions() reconstructs the
effective version list from the range for backward-compat with tier-check.
Closes #256.

Author: claude

src/scenarios/authorization-server/authorization-server-metadata.ts

@@ -4,15 +4,15 @@
 import {
   ClientScenarioForAuthorizationServer,
   ConformanceCheck,
-  SpecVersion
+  DatedSpecVersion
 } from '../../types';
 import { request } from 'undici';
 
 type Status = 'SUCCESS' | 'FAILURE';
 
 export class AuthorizationServerMetadataEndpointScenario implements ClientScenarioForAuthorizationServer {
   name = 'authorization-server-metadata-endpoint';
-  specVersions: SpecVersion[] = ['2025-03-26', '2025-06-18', '2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-03-26';
   description = `Test authorization server metadata endpoint.
 
 **Authorization Server Implementation Requirements:**

src/scenarios/client/auth/basic-cimd.ts

@@ -1,5 +1,5 @@
 import type { Scenario, ConformanceCheck } from '../../../types';
-import { ScenarioUrls, SpecVersion } from '../../../types';
+import { ScenarioUrls, DatedSpecVersion } from '../../../types';
 import { createAuthServer } from './helpers/createAuthServer';
 import { createServer } from './helpers/createServer';
 import { ServerLifecycle } from './helpers/serverLifecycle';
@@ -22,7 +22,7 @@ export const CIMD_CLIENT_METADATA_URL =
  */
 export class AuthBasicCIMDScenario implements Scenario {
   name = 'auth/basic-cimd';
-  specVersions: SpecVersion[] = ['2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-11-25';
   description =
     'Tests OAuth flow with Client ID Metadata Documents (SEP-991/URL-based client IDs). Server advertises client_id_metadata_document_supported=true and client should use URL as client_id instead of DCR.';
   private authServer = new ServerLifecycle();

src/scenarios/client/auth/client-credentials.ts

@@ -4,8 +4,9 @@ import type {
   Scenario,
   ConformanceCheck,
   ScenarioUrls,
-  ScenarioSpecTag
+  SpecVersion
 } from '../../../types';
+import { LATEST_SPEC_VERSION } from '../../../types';
 import { createAuthServer } from './helpers/createAuthServer';
 import { createServer } from './helpers/createServer';
 import { ServerLifecycle } from './helpers/serverLifecycle';
@@ -37,7 +38,8 @@ async function generateTestKeypair(): Promise<{
  */
 export class ClientCredentialsJwtScenario implements Scenario {
   name = 'auth/client-credentials-jwt';
-  specVersions: ScenarioSpecTag[] = ['extension'];
+  extension = true;
+  introducedIn: SpecVersion = LATEST_SPEC_VERSION;
   description =
     'Tests OAuth client_credentials flow with private_key_jwt authentication (SEP-1046)';
 
@@ -256,7 +258,8 @@ export class ClientCredentialsJwtScenario implements Scenario {
  */
 export class ClientCredentialsBasicScenario implements Scenario {
   name = 'auth/client-credentials-basic';
-  specVersions: ScenarioSpecTag[] = ['extension'];
+  extension = true;
+  introducedIn: SpecVersion = LATEST_SPEC_VERSION;
   description =
     'Tests OAuth client_credentials flow with client_secret_basic authentication';
 

src/scenarios/client/auth/cross-app-access.ts

@@ -5,8 +5,9 @@ import type {
   Scenario,
   ConformanceCheck,
   ScenarioUrls,
-  ScenarioSpecTag
+  SpecVersion
 } from '../../../types';
+import { LATEST_SPEC_VERSION } from '../../../types';
 import { createAuthServer } from './helpers/createAuthServer';
 import { createServer } from './helpers/createServer';
 import { MockTokenVerifier } from './helpers/mockTokenVerifier';
@@ -60,7 +61,8 @@ async function createIdpIdToken(
  */
 export class CrossAppAccessCompleteFlowScenario implements Scenario {
   name = 'auth/cross-app-access-complete-flow';
-  specVersions: ScenarioSpecTag[] = ['extension'];
+  extension = true;
+  introducedIn: SpecVersion = LATEST_SPEC_VERSION;
   description =
     'Tests complete SEP-990 flow: token exchange + JWT bearer grant (Enterprise Managed OAuth)';
 

src/scenarios/client/auth/discovery-metadata.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Scenario, ConformanceCheck } from '../../../types';
-import { ScenarioUrls } from '../../../types';
+import { ScenarioUrls, DatedSpecVersion } from '../../../types';
 import { createAuthServer } from './helpers/createAuthServer';
 import { createServer } from './helpers/createServer';
 import { ServerLifecycle } from './helpers/serverLifecycle';
@@ -87,7 +87,7 @@ function createMetadataScenario(config: MetadataScenarioConfig): Scenario {
 
   return {
     name: `auth/${config.name}`,
-    specVersions: ['2025-11-25'],
+    introducedIn: '2025-11-25' as DatedSpecVersion,
     description: `Tests Basic OAuth metadata discovery flow.
 
 **PRM:** ${config.prmLocation}${config.inWwwAuth ? '' : ' (not in WWW-Authenticate)'}

src/scenarios/client/auth/march-spec-backcompat.ts

@@ -1,5 +1,5 @@
 import type { Scenario, ConformanceCheck } from '../../../types';
-import { ScenarioUrls, SpecVersion } from '../../../types';
+import { ScenarioUrls, DatedSpecVersion } from '../../../types';
 import { createAuthServer } from './helpers/createAuthServer';
 import { createServer } from './helpers/createServer';
 import { ServerLifecycle } from './helpers/serverLifecycle';
@@ -8,7 +8,8 @@ import { SpecReferences } from './spec-references';
 
 export class Auth20250326OAuthMetadataBackcompatScenario implements Scenario {
   name = 'auth/2025-03-26-oauth-metadata-backcompat';
-  specVersions: SpecVersion[] = ['2025-03-26'];
+  introducedIn: DatedSpecVersion = '2025-03-26';
+  removedIn: DatedSpecVersion = '2025-06-18';
   description =
     'Tests 2025-03-26 spec OAuth flow: no PRM (Protected Resource Metadata), OAuth metadata at root location';
   private server = new ServerLifecycle();
@@ -69,7 +70,8 @@ export class Auth20250326OAuthMetadataBackcompatScenario implements Scenario {
 
 export class Auth20250326OEndpointFallbackScenario implements Scenario {
   name = 'auth/2025-03-26-oauth-endpoint-fallback';
-  specVersions: SpecVersion[] = ['2025-03-26'];
+  introducedIn: DatedSpecVersion = '2025-03-26';
+  removedIn: DatedSpecVersion = '2025-06-18';
   description =
     'Tests OAuth flow with no metadata endpoints, relying on fallback to standard OAuth endpoints at server root (2025-03-26 spec behavior)';
   private server = new ServerLifecycle();

src/scenarios/client/auth/offline-access.ts

@@ -27,7 +27,7 @@ import { MockTokenVerifier } from './helpers/mockTokenVerifier';
  */
 export class OfflineAccessScopeScenario implements Scenario {
   name = 'auth/offline-access-scope';
-  specVersions: SpecVersion[] = [DRAFT_PROTOCOL_VERSION];
+  introducedIn: SpecVersion = DRAFT_PROTOCOL_VERSION;
   description =
     'Tests that a client that wants a refresh token handles offline_access scope and refresh_token grant type when AS supports them (SEP-2207)';
 
@@ -231,7 +231,7 @@ export class OfflineAccessScopeScenario implements Scenario {
  */
 export class OfflineAccessNotSupportedScenario implements Scenario {
   name = 'auth/offline-access-not-supported';
-  specVersions: SpecVersion[] = [DRAFT_PROTOCOL_VERSION];
+  introducedIn: SpecVersion = DRAFT_PROTOCOL_VERSION;
   description =
     'Tests that client does not request offline_access when AS does not list it in scopes_supported (SEP-2207)';
 

src/scenarios/client/auth/pre-registration.ts

@@ -2,7 +2,7 @@ import type {
   Scenario,
   ConformanceCheck,
   ScenarioUrls,
-  SpecVersion
+  DatedSpecVersion
 } from '../../../types';
 import { createAuthServer } from './helpers/createAuthServer';
 import { createServer } from './helpers/createServer';
@@ -24,7 +24,7 @@ const PRE_REGISTERED_CLIENT_SECRET = 'pre-registered-secret';
  */
 export class PreRegistrationScenario implements Scenario {
   name = 'auth/pre-registration';
-  specVersions: SpecVersion[] = ['2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-11-25';
   description =
     'Tests OAuth flow with pre-registered client credentials. Server does not support DCR.';
 

src/scenarios/client/auth/resource-mismatch.ts

@@ -31,7 +31,7 @@ import { MockTokenVerifier } from './helpers/mockTokenVerifier.js';
  */
 export class ResourceMismatchScenario implements Scenario {
   name = 'auth/resource-mismatch';
-  specVersions: SpecVersion[] = [DRAFT_PROTOCOL_VERSION];
+  introducedIn: SpecVersion = DRAFT_PROTOCOL_VERSION;
   description =
     'Tests that client rejects when PRM resource does not match server URL';
   allowClientError = true;

src/scenarios/client/auth/scope-handling.ts

@@ -1,5 +1,5 @@
 import type { Scenario, ConformanceCheck } from '../../../types';
-import { ScenarioUrls, SpecVersion } from '../../../types';
+import { ScenarioUrls, DatedSpecVersion } from '../../../types';
 import { createAuthServer } from './helpers/createAuthServer';
 import { createServer } from './helpers/createServer';
 import { ServerLifecycle } from './helpers/serverLifecycle';
@@ -15,7 +15,7 @@ import type { Request, Response, NextFunction } from 'express';
  */
 export class ScopeFromWwwAuthenticateScenario implements Scenario {
   name = 'auth/scope-from-www-authenticate';
-  specVersions: SpecVersion[] = ['2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-11-25';
   description =
     'Tests that client uses scope parameter from WWW-Authenticate header when provided';
   private authServer = new ServerLifecycle();
@@ -101,7 +101,7 @@ export class ScopeFromWwwAuthenticateScenario implements Scenario {
  */
 export class ScopeFromScopesSupportedScenario implements Scenario {
   name = 'auth/scope-from-scopes-supported';
-  specVersions: SpecVersion[] = ['2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-11-25';
   description =
     'Tests that client uses all scopes from scopes_supported when scope not in WWW-Authenticate header';
   private authServer = new ServerLifecycle();
@@ -197,7 +197,7 @@ export class ScopeFromScopesSupportedScenario implements Scenario {
  */
 export class ScopeOmittedWhenUndefinedScenario implements Scenario {
   name = 'auth/scope-omitted-when-undefined';
-  specVersions: SpecVersion[] = ['2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-11-25';
   description =
     'Tests that client omits scope parameter when scopes_supported is undefined';
   private authServer = new ServerLifecycle();
@@ -284,7 +284,7 @@ export class ScopeOmittedWhenUndefinedScenario implements Scenario {
  */
 export class ScopeStepUpAuthScenario implements Scenario {
   name = 'auth/scope-step-up';
-  specVersions: SpecVersion[] = ['2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-11-25';
   description =
     'Tests that client handles step-up authentication with different scope requirements per operation';
   private authServer = new ServerLifecycle();
@@ -481,7 +481,7 @@ export class ScopeStepUpAuthScenario implements Scenario {
  */
 export class ScopeRetryLimitScenario implements Scenario {
   name = 'auth/scope-retry-limit';
-  specVersions: SpecVersion[] = ['2025-11-25'];
+  introducedIn: DatedSpecVersion = '2025-11-25';
   description =
     'Tests that client implements retry limits to prevent infinite authorization loops on repeated 403 responses';
   allowClientError = true;