1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

// ============================================
// SOURCE COMPATIBILITY EXAMPLES
// ============================================
 
// Original interface
interface DocumentService {
    getDocument(id: string): Document;
    saveDocument(doc: Document): void;
}
 
// Change A: Add optional parameter (SOURCE COMPATIBLE ✓)
interface DocumentServiceV2A {
    getDocument(id: string, options?: GetOptions): Document;  // ✓ Old calls still work
    saveDocument(doc: Document): void;
}
 
// Change B: Add required parameter (BREAKS SOURCE COMPATIBILITY ✗)
interface DocumentServiceV2B {
    getDocument(id: string, userId: string): Document;  // ✗ Old calls fail to compile
    saveDocument(doc: Document): void;
}
 
// Change C: Add new method (MAY BREAK - depends on language)
interface DocumentServiceV2C {
    getDocument(id: string): Document;
    saveDocument(doc: Document): void;
    deleteDocument(id: string): void;  // ✗ Implementers must add method
}
 
// Change D: Remove method (BREAKS SOURCE COMPATIBILITY ✗)
interface DocumentServiceV2D {
    getDocument(id: string): Document;
    // saveDocument removed  // ✗ Callers can't save
}
 
// ============================================
// BEHAVIORAL COMPATIBILITY EXAMPLES
// ============================================
 
// Original contract (implicit)
// getDocument(id) returns null if document doesn't exist
 
// Change that breaks behavioral compatibility:
// getDocument(id) now throws DocumentNotFoundError if doesn't exist
// 
// Source compatible: signature unchanged
// Behaviorally incompatible: callers expecting null will crash
 
// Original implementation
class OldImplementation implements DocumentService {
    getDocument(id: string): Document | null {
        const doc = this.db.find(id);
        return doc ?? null;  // Returns null if not found
    }
}
 
// New implementation (source compatible, behaviorally different!)
class NewImplementation implements DocumentService {
    getDocument(id: string): Document {
        const doc = this.db.find(id);
        if (!doc) throw new DocumentNotFoundError(id);  // Throws if not found!
        return doc;
    }
}
 
// Client code that relied on null return:
function oldClientCode(service: DocumentService) {
    const doc = service.getDocument('some-id');
    if (doc === null) {
        showNotFoundMessage();  // Never executes with new implementation!
    }
    // ... crash on line where doc.title is accessed
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

// ============================================
// VERSION 1.x: Fat Interface Era
// ============================================
 
// v1.0.0 - Initial release
interface IUserService {
    login(email: string, password: string): User;
    getProfile(userId: string): UserProfile;
}
 
// v1.1.0 - MINOR: Added logout (non-breaking)
interface IUserService {
    login(email: string, password: string): User;
    logout(userId: string): void;  // Added (consumers don't call it yet)
    getProfile(userId: string): UserProfile;
}
 
// v1.2.0 - MINOR: Added optional parameter (non-breaking)
interface IUserService {
    login(email: string, password: string, rememberMe?: boolean): User;  // Optional param
    logout(userId: string): void;
    getProfile(userId: string): UserProfile;
}
 
// ============================================
// VERSION 2.x: Interface Split Era
// ============================================
 
// v2.0.0 - MAJOR: New focused interfaces introduced
// IUserService still exists but is deprecated
 
interface Authenticator {
    login(email: string, password: string, rememberMe?: boolean): User;
    logout(userId: string): void;
}
 
interface ProfileProvider {
    getProfile(userId: string): UserProfile;
}
 
/**
 * @deprecated since v2.0.0, use Authenticator and ProfileProvider
 * @see Authenticator
 * @see ProfileProvider
 */
interface IUserService extends Authenticator, ProfileProvider {
    // Now defined as composition of new interfaces
    // Existing consumers still work!
}
 
// v2.1.0 - MINOR: Added method to ProfileProvider
interface ProfileProvider {
    getProfile(userId: string): UserProfile;
    updateProfile(userId: string, profile: Partial<UserProfile>): void;  // Added
}
 
// IUserService automatically gains the new method through inheritance
 
// ============================================
// VERSION 3.x: Facade Removal Era
// ============================================
 
// v3.0.0 - MAJOR: IUserService removed
// Only Authenticator and ProfileProvider exist
// This is the breaking change consumers were warned about
 
// UPGRADE GUIDE v2.x → v3.x:
// 
// BEFORE:
// function oldCode(service: IUserService) {
//     service.login(email, password);
//     service.getProfile(userId);
// }
// 
// AFTER:
// function newCode(auth: Authenticator, profile: ProfileProvider) {
//     auth.login(email, password);
//     profile.getProfile(userId);
// }
 
// ============================================
// VERSIONED PACKAGE STRUCTURE
// ============================================
 
// package.json for library with semantic versioning
{
    "name": "@company/user-service",
    "version": "2.3.1",
    
    // Exports with explicit versioning
    "exports": {
        // Current version
        "./authenticator": "./dist/v2/authenticator.js",
        "./profile-provider": "./dist/v2/profile-provider.js",
        
        // Legacy v1 interface (deprecated but available)
        "./legacy": "./dist/v1/user-service.js",
        
        // Compatibility layer
        "./compat": "./dist/compat/user-service-shim.js"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174

// ============================================
// THE INTERFACES
// ============================================
 
// Old fat interface (legacy)
interface LegacyFileSystem {
    readFile(path: string): string;
    writeFile(path: string, content: string): void;
    deleteFile(path: string): void;
    listDirectory(path: string): string[];
    createDirectory(path: string): void;
    deleteDirectory(path: string): void;
    exists(path: string): boolean;
    stat(path: string): FileStat;
}
 
// New focused interfaces
interface FileReader {
    read(path: string): string;
    exists(path: string): boolean;
}
 
interface FileWriter {
    write(path: string, content: string): void;
    delete(path: string): void;
}
 
interface DirectoryManager {
    list(path: string): string[];
    create(path: string): void;
    delete(path: string): void;
}
 
interface FileInspector {
    stat(path: string): FileStat;
    exists(path: string): boolean;
}
 
// ============================================
// FORWARD ADAPTER: New → Old
// Lets legacy consumers use new implementations
// ============================================
 
class LegacyFileSystemAdapter implements LegacyFileSystem {
    constructor(
        private reader: FileReader,
        private writer: FileWriter,
        private directories: DirectoryManager,
        private inspector: FileInspector
    ) {}
    
    // Delegate to new interfaces, matching old method names
    
    readFile(path: string): string {
        return this.reader.read(path);  // read → readFile
    }
    
    writeFile(path: string, content: string): void {
        this.writer.write(path, content);  // write → writeFile
    }
    
    deleteFile(path: string): void {
        this.writer.delete(path);  // delete → deleteFile
    }
    
    listDirectory(path: string): string[] {
        return this.directories.list(path);  // list → listDirectory
    }
    
    createDirectory(path: string): void {
        this.directories.create(path);  // create → createDirectory
    }
    
    deleteDirectory(path: string): void {
        this.directories.delete(path);  // delete → deleteDirectory
    }
    
    exists(path: string): boolean {
        return this.reader.exists(path);  // Could use inspector too
    }
    
    stat(path: string): FileStat {
        return this.inspector.stat(path);
    }
}
 
// Usage: Legacy consumer gets adapter instance
function legacyCode(fs: LegacyFileSystem) {
    const content = fs.readFile('/data/config.json');
    fs.writeFile('/data/config.backup.json', content);
}
 
// Behind the scenes, new implementations are used:
const adapter = new LegacyFileSystemAdapter(
    new LocalFileReader(),
    new LocalFileWriter(),
    new LocalDirectoryManager(),
    new LocalFileInspector()
);
 
legacyCode(adapter);  // Legacy code runs with new infrastructure
 
// ============================================
// REVERSE ADAPTER: Old → New
// Lets new consumers use old implementations during migration
// ============================================
 
class FileReaderFromLegacy implements FileReader {
    constructor(private legacy: LegacyFileSystem) {}
    
    read(path: string): string {
        return this.legacy.readFile(path);  // readFile → read
    }
    
    exists(path: string): boolean {
        return this.legacy.exists(path);
    }
}
 
class FileWriterFromLegacy implements FileWriter {
    constructor(private legacy: LegacyFileSystem) {}
    
    write(path: string, content: string): void {
        this.legacy.writeFile(path, content);  // writeFile → write
    }
    
    delete(path: string): void {
        this.legacy.deleteFile(path);  // deleteFile → delete
    }
}
 
// Usage: New consumers can use old implementation
function newCode(reader: FileReader, writer: FileWriter) {
    const content = reader.read('/data/config.json');
    writer.write('/data/config.backup.json', content);
}
 
// Wrap old implementation in adapters:
const legacyFS = new OldFileSystemImplementation();
newCode(
    new FileReaderFromLegacy(legacyFS),
    new FileWriterFromLegacy(legacyFS)
);
 
// ============================================
// PARTIAL ADAPTER: Subset Adaptation
// For specific use cases that don't need full interface
// ============================================
 
// Some consumers only need read-only access
interface ReadOnlyFileSystem {
    readFile(path: string): string;
    listDirectory(path: string): string[];
    exists(path: string): boolean;
}
 
// Partial adapter from full interface
class ReadOnlyFileSystemAdapter implements ReadOnlyFileSystem {
    constructor(private full: LegacyFileSystem) {}
    
    readFile(path: string): string {
        return this.full.readFile(path);
    }
    
    listDirectory(path: string): string[] {
        return this.full.listDirectory(path);
    }
    
    exists(path: string): boolean {
        return this.full.exists(path);
    }
    
    // Write methods NOT exposed - intentionally restricted
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

// ============================================
// STRATEGY 1: Namespaced Versions
// Each version lives in its own namespace
// ============================================
 
// V1 namespace - original interfaces
namespace UserServiceV1 {
    export interface IUserService {
        login(email: string, password: string): User;
        getProfile(userId: string): UserProfile;
        updateProfile(userId: string, profile: UserProfile): void;
    }
    
    export class UserService implements IUserService {
        // V1 implementation
    }
}
 
// V2 namespace - focused interfaces
namespace UserServiceV2 {
    export interface Authenticator {
        login(email: string, password: string): User;
        logout(userId: string): void;
    }
    
    export interface ProfileManager {
        getProfile(userId: string): UserProfile;
        updateProfile(userId: string, profile: UserProfile): void;
    }
    
    export class AuthenticationService implements Authenticator {
        // V2 implementation
    }
    
    export class ProfileService implements ProfileManager {
        // V2 implementation
    }
}
 
// Consumers explicitly choose their version:
import { IUserService } from './user-service/v1';  // Legacy consumer
import { Authenticator } from './user-service/v2'; // Modern consumer
 
// ============================================
// STRATEGY 2: Default Export with Legacy Re-export
// Make new version the default, provide legacy as opt-in
// ============================================
 
// user-service/index.ts (default exports V2)
export { Authenticator, ProfileManager } from './v2';
 
// user-service/legacy.ts (explicit legacy import)
export { IUserService } from './v1';
 
// Usage:
import { Authenticator } from '@company/user-service';  // Gets V2
import { IUserService } from '@company/user-service/legacy';  // Explicit V1
 
// ============================================
// STRATEGY 3: Version Detection and Auto-Adaptation
// Detect which version consumer expects, adapt automatically
// ============================================
 
type InterfaceVersion = 'v1' | 'v2';
 
class VersionedUserServiceFactory {
    constructor(
        private v1Impl: UserServiceV1.IUserService,
        private v2Auth: UserServiceV2.Authenticator,
        private v2Profile: UserServiceV2.ProfileManager
    ) {}
    
    // Create the appropriate version
    create(version: InterfaceVersion): UserServiceV1.IUserService | UserServiceV2Bundle {
        switch (version) {
            case 'v1':
                // Return V1 interface, possibly wrapping V2 implementations
                return new V1AdapterOverV2(this.v2Auth, this.v2Profile);
            case 'v2':
                return {
                    auth: this.v2Auth,
                    profile: this.v2Profile
                };
        }
    }
    
    // Auto-detect from calling context (if possible)
    auto(): UserServiceV1.IUserService | UserServiceV2Bundle {
        const requestedVersion = this.detectRequestedVersion();
        return this.create(requestedVersion);
    }
    
    private detectRequestedVersion(): InterfaceVersion {
        // Could detect from:
        // - HTTP header: X-API-Version: v1
        // - Package version constraint
        // - Feature flag
        // - Consumer ID in registry
        return 'v2';  // Default to latest
    }
}
 
// ============================================
// STRATEGY 4: Maintenance Branches
// For long-term support of old versions
// ============================================
 
/**
 * Repository Structure:
 * 
 * main branch (development)
 *   └── src/v3/  (current development)
 * 
 * release/v2.x (maintenance)
 *   └── src/     (v2.x bugfixes only)
 * 
 * release/v1.x (extended support)
 *   └── src/     (critical security fixes only)
 * 
 * Version Support Policy:
 * - Current version (v3): Full support
 * - Previous version (v2): Bug fixes for 12 months
 * - Older versions (v1): Security fixes for 24 months
 */
 
// ============================================
// STRATEGY 5: Interface Capability Detection
// Runtime detection of available capabilities
// ============================================
 
interface CapabilityAware {
    readonly capabilities: Set<string>;
    hasCapability(cap: string): boolean;
}
 
class AdaptiveUserService implements CapabilityAware {
    readonly capabilities = new Set([
        'authentication',
        'profile',
        'administration',  // Might not be available in all deployments
    ]);
    
    hasCapability(cap: string): boolean {
        return this.capabilities.has(cap);
    }
    
    // Graceful degradation for optional capabilities
    getAdminInterface(): UserAdministrator | null {
        if (this.hasCapability('administration')) {
            return this.adminService;
        }
        return null;  // Capability not available
    }
}
 
// Consumer code handles capability presence/absence:
function maybeAdminAction(service: CapabilityAware & Partial<AdminCapable>) {
    if (service.hasCapability('administration')) {
        service.getAdminInterface()?.listAllUsers();
    } else {
        showNotAuthorizedMessage();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

// ============================================
// GRACEFUL BREAKING CHANGE PROCESS
// ============================================
 
/**
 * TIMELINE for breaking IUserService into focused interfaces:
 * 
 * T-6 months: ANNOUNCEMENT
 *   - Write migration guide
 *   - Add @deprecated annotation with removal version
 *   - Create focused interfaces alongside old one
 *   - Start tracking usage of deprecated interface
 * 
 * T-4 months: SOFT WARNINGS
 *   - Console.warn() on deprecated usage (dev only)
 *   - Send periodic reports to consuming teams
 *   - Hold office hours for migration questions
 * 
 * T-2 months: LOUD WARNINGS  
 *   - Log deprecation warnings in production (not console, to telemetry)
 *   - Require @SuppressWarnings annotation to silence
 *   - Escalate to team leads for unmigrated services
 * 
 * T-0: REMOVAL
 *   - Remove deprecated interface
 *   - Remove compatibility adapters
 *   - Major version bump
 *   - Update all documentation
 * 
 * T+2 weeks: CLEANUP
 *   - Remove migration tracking
 *   - Archive migration guides
 */
 
// ============================================
// COMMUNICATION TEMPLATES
// ============================================
 
const announcementTemplate = `
Subject: [Action Required] IUserService Deprecation - Migrate by 2024-06-01
 
Dear Consumers,
 
We are deprecating \`IUserService\` in favor of focused interfaces:
- \`Authenticator\` - login/logout operations
- \`ProfileManager\` - profile operations
- \`UserAdministrator\` - admin operations
 
WHY: The fat interface forces unnecessary dependencies and complicates testing.
The new interfaces are simpler, more testable, and better aligned with ISP.
 
TIMELINE:
- 2024-01-01: New interfaces available, old interface deprecated
- 2024-04-01: Deprecation warnings in logs
- 2024-06-01: Old interface REMOVED (breaking change)
 
MIGRATION GUIDE: https://docs.example.com/migrations/user-service-split
 
SUPPORT: Join #user-service-migration Slack channel
         Office hours every Tuesday 2-3pm
 
TRACKING: Your team's migration status:
- auth-service: ✅ Migrated
- profile-ui: ⚠️ 2 usages remaining
- admin-panel: ❌ 8 usages remaining
 
Please complete migration by 2024-05-15 to allow buffer for issues.
 
Questions? Reply to this email or join office hours.
 
Best,
Platform Team
`;
 
// ============================================
// FORCED MIGRATION FOR STRAGGLERS
// ============================================
 
/**
 * When deadline passes and some consumers haven't migrated:
 * 
 * Option A: EXTEND DEADLINE
 *   - If legitimate blockers exist
 *   - If majority still unmigrated
 *   - If team lacks capacity to help
 * 
 * Option B: MIGRATE FOR THEM
 *   - Platform team makes changes in their repos
 *   - Review with consuming team
 *   - Useful for mechanical migrations
 * 
 * Option C: BREAK AND SUPPORT
 *   - Remove interface as announced
 *   - Be available to urgently help fix breaks
 *   - Acceptable if breaks are obvious and easy to fix
 * 
 * Option D: TEMPORARY EXEMPTION
 *   - Create special build for unmigrated consumers
 *   - Time-limited, with clear final deadline
 *   - Requires VP approval
 */
 
// Automated "migrate for them" script
async function migrateRepository(repoPath: string): Promise<MigrationResult> {
    // Run codemod
    await runCodemod(repoPath, 'migrate-user-service');
    
    // Run tests
    const testResult = await runTests(repoPath);
    if (!testResult.passed) {
        return { success: false, reason: 'Tests failed', details: testResult };
    }
    
    // Create PR
    const pr = await createPullRequest(repoPath, {
        title: '[AUTO] Migrate from IUserService to focused interfaces',
        body: migrationPRTemplate,
        reviewers: await getCodeOwners(repoPath)
    });
    
    return { success: true, prUrl: pr.url };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

// ============================================
// VISIBILITY-BASED COMPATIBILITY STRATEGIES
// ============================================
 
// PUBLIC API: Highest compatibility requirements
// Used by external customers, requires formal versioning
 
// v1 API - must remain stable
export namespace PublicAPI {
    /** 
     * @public
     * @stability Stable - breaking changes require major version bump
     */
    export interface UserAPI {
        readonly userId: string;
        getProfile(): Promise<UserProfileDTO>;
        updateProfile(updates: Partial<UserProfileDTO>): Promise<void>;
    }
    
    // Any change to UserAPI is:
    // 1. Reviewed by API council
    // 2. Documented in CHANGELOG
    // 3. Announced to customers
    // 4. Deprecated for 1 year before removal
}
 
// INTERNAL API: Moderate compatibility requirements
// Used by other teams, coordination possible
 
/** 
 * @internal
 * @stability Evolving - deprecation required before changes
 */
export interface InternalUserService {
    login(credentials: Credentials): Promise<Session>;
    getUser(id: string): Promise<User>;
}
 
// Changes to InternalUserService:
// 1. Announced in #platform-updates Slack
// 2. 3-month deprecation period
// 3. Help provided if requested
 
// MODULE-INTERNAL: Minimal compatibility requirements
// Only used within this module
 
/** 
 * @private
 * @stability Unstable - may change without notice
 */
interface UserRepositoryImpl {
    findById(id: string): User | null;
    save(user: User): void;
}
 
// Changes to UserRepositoryImpl:
// Just update and fix all call sites in same PR
 
// ============================================
// VISIBILITY MARKERS IN CODE
// ============================================
 
/**
 * TypeScript approach: Use module boundaries + documentation
 */
 
// user-service/
// ├── public/           # Exported for external use
// │   └── types.ts      # User, Profile (stable)
// ├── internal/         # Exported for internal org use  
// │   └── service.ts    # UserService (evolving)
// └── impl/             # Not exported
//     └── repository.ts # DB access (unstable)
 
// user-service/index.ts
export * from './public/types';      // Public API
export * from './internal/service';  // Internal API
// impl/* not exported - true private

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

// ============================================
// INTERFACE DOCUMENTATION TEMPLATE
// ============================================
 
/**
 * Authenticator - Responsible for user authentication operations.
 * 
 * @stability Stable
 * @since 2.0.0
 * @see {@link ProfileManager} for profile operations
 * @see {@link UserAdministrator} for admin operations
 * 
 * ## Overview
 * This interface provides authentication capabilities including login,
 * logout, and session validation. It replaces the authentication
 * methods from the deprecated `IUserService`.
 * 
 * ## Stability Guarantees
 * - Method signatures will not change within major version
 * - New methods may be added in minor versions (will have defaults)
 * - Behavioral contracts documented below will be honored
 * 
 * ## Behavioral Contracts
 * 
 * ### login()
 * - Returns User object on successful authentication
 * - Throws `InvalidCredentialsError` if email/password incorrect
 * - Throws `AccountLockedError` if account is locked
 * - Throws `RateLimitError` if too many attempts (>5 in 5 minutes)
 * - Creates a session valid for 24 hours
 * 
 * ### logout()
 * - Invalidates all sessions for the user
 * - Is idempotent (calling on logged-out user is safe)
 * - Never throws (errors are logged but not propagated)
 * 
 * ## Migration from IUserService
 * Replace `userService.login()` with `authenticator.login()`.
 * Behavior is identical.
 * 
 * @example
 * ```typescript
 * const auth: Authenticator = container.get(Authenticator);
 * 
 * try {
 *     const user = await auth.login('user@example.com', 'password');
 *     console.log(`Logged in as ${user.name}`);
 * } catch (error) {
 *     if (error instanceof InvalidCredentialsError) {
 *         showLoginError('Invalid email or password');
 *     }
 * }
 * ```
 */
interface Authenticator {
    /**
     * Authenticates a user with email and password.
     * 
     * @param email - User's email address (case-insensitive)
     * @param password - User's password (case-sensitive)
     * @returns The authenticated User object
     * @throws {InvalidCredentialsError} If credentials are incorrect
     * @throws {AccountLockedError} If account is locked
     * @throws {RateLimitError} If rate limit exceeded
     */
    login(email: string, password: string): Promise<User>;
    
    /**
     * Logs out a user by invalidating all their sessions.
     * 
     * This operation is idempotent - calling it multiple times
     * or on an already logged-out user has no adverse effects.
     * 
     * @param userId - The ID of the user to log out
     */
    logout(userId: string): Promise<void>;
}
 
// ============================================
// CHANGELOG DOCUMENTATION
// ============================================
 
/**
 * CHANGELOG.md
 * 
 * ## [3.0.0] - 2024-06-01
 * 
 * ### ⚠️ BREAKING CHANGES
 * 
 * - Removed `IUserService` interface (deprecated since 2.0.0)
 *   - Use `Authenticator` for login/logout
 *   - Use `ProfileManager` for profile operations
 *   - Use `UserAdministrator` for admin operations
 *   - See migration guide: docs/migrations/user-service-split.md
 * 
 * - Removed `UserService` class facade
 *   - Inject specific interfaces directly via DI
 * 
 * ### Added
 * 
 * - `Authenticator.validateSession()` method for session checks
 * 
 * ---
 * 
 * ## [2.3.0] - 2024-04-15
 * 
 * ### Added
 * 
 * - `ProfileManager.deleteProfile()` method
 * 
 * ### Deprecated
 * 
 * - `IUserService` interface (will be removed in 3.0.0)
 *   - Runtime warnings now logged when used
 *   - See migration guide: docs/migrations/user-service-split.md
 * 
 * ---
 * 
 * ## [2.0.0] - 2024-01-01
 * 
 * ### Added
 * 
 * - `Authenticator` interface for authentication
 * - `ProfileManager` interface for profiles
 * - `UserAdministrator` interface for admin operations
 * 
 * ### Deprecated
 * 
 * - `IUserService` interface
 *   - Replaced by focused interfaces above
 *   - Will be removed in 3.0.0
 *   - Legacy interface remains functional via facade
 */