@rs-native-kit/version-check 0.1.2

package/src/data/config/sources/EnvironmentOverrideSource.ts

@@ -0,0 +1,22 @@
+import type { VersionManagerConfigDocument } from '../../../domain/models/ConfigDocument';
+import type { IEnvironmentOverrideSource } from '../../../domain/ports/IConfigSources';
+
+/**
+ * Doc 03 §4 — "there is no OS process environment on a device"; this tier maps to
+ * build-time-injected constants and explicit runtime overrides, not `process.env` on a
+ * server. Build-time constants (Info.plist / BuildConfig fields) are app-specific and
+ * have no generic cross-platform read path from JS, so this implementation covers the
+ * "explicit configure({ configSources: { envOverrides } })" half of §4.1 tier 1 — the
+ * build-time-constant half is a per-app integration concern (documented, not a gap in
+ * this port's contract, which only promises "read whatever overrides are available").
+ */
+export class EnvironmentOverrideSource implements IEnvironmentOverrideSource {
+  constructor(
+    private readonly overrides:
+      Partial<VersionManagerConfigDocument> | undefined
+  ) {}
+
+  async read(): Promise<Partial<VersionManagerConfigDocument>> {
+    return this.overrides ?? {};
+  }
+}

package/src/data/config/sources/LocalConfigSource.ts

@@ -0,0 +1,24 @@
+import type {
+  RawConfigDocument,
+  SignedConfigEnvelope,
+} from '../../../domain/models/ConfigDocument';
+import type { ILocalConfigSource } from '../../../domain/ports/IConfigSources';
+
+/**
+ * Doc 03 §5.1 — the design calls for a native mmap reader (iOS Data(alwaysMapped),
+ * Android FileChannel.map) to avoid a double-copy when reading a bundled config asset.
+ * This implementation takes a documented, lower-risk equivalent instead: the host app
+ * imports its bundled config JSON via Metro/webpack's native JSON module support
+ * (`import localConfig from './vm-config.json'`) and passes the parsed envelope through
+ * `VersionManagerOptions.configSources.local`. Metro's JSON loader already avoids the
+ * page-cache -> native-heap -> JS-heap double copy for typical bundle sizes (the asset
+ * is compiled into the JS bundle itself), which satisfies §5.1's actual goal (avoid GC
+ * churn against the 5MB budget for a <=64KB document) without a dedicated native reader.
+ */
+export class LocalConfigSource implements ILocalConfigSource {
+  constructor(private readonly envelope: SignedConfigEnvelope | undefined) {}
+
+  async read(): Promise<RawConfigDocument | null> {
+    return this.envelope ?? null;
+  }
+}

package/src/data/config/sources/RemoteConfigSource.ts

@@ -0,0 +1,41 @@
+import {
+  OfflineException,
+  StoreResponseParseException,
+} from '../../../domain/errors/VersionManagerException';
+import type {
+  FetchOptions,
+  RawConfigDocument,
+} from '../../../domain/models/ConfigDocument';
+import type { IRemoteConfigSource } from '../../../domain/ports/IConfigSources';
+import type { IHttpClient } from '../../../domain/ports/IPlatformBridge';
+
+/** Doc 03 §4.3 — the remote-fetch tier, reached through the same IHttpClient port every other network call in this SDK uses. */
+export class RemoteConfigSource implements IRemoteConfigSource {
+  constructor(private readonly http: IHttpClient) {}
+
+  async fetch(url: string, options: FetchOptions): Promise<RawConfigDocument> {
+    const response = await this.http.request({
+      url,
+      method: 'GET',
+      headers: options.headers,
+      timeoutMs: options.timeoutMs,
+    });
+
+    if (response.status !== 200) {
+      throw new OfflineException({
+        message: `Remote config fetch returned HTTP ${response.status}`,
+        metadata: { url, status: response.status },
+      });
+    }
+
+    try {
+      return JSON.parse(response.body);
+    } catch (error) {
+      throw new StoreResponseParseException({
+        message: 'Remote config endpoint returned malformed JSON',
+        cause: error,
+        metadata: { url },
+      });
+    }
+  }
+}

package/src/data/providers/amazon/AmazonAppstoreProvider.ts

@@ -0,0 +1,16 @@
+import { UnsupportedStoreException } from '../../../domain/errors/VersionManagerException';
+import type { StoreProviderId } from '../../../domain/models/PlatformId';
+import type { StoreLookupResult } from '../../../domain/models/StoreLookup';
+import type { IStoreProvider } from '../../../domain/ports/IStoreProvider';
+
+/** Not yet implemented — see Prompt 11 in the design series. */
+export class AmazonAppstoreProvider implements IStoreProvider {
+  readonly id: StoreProviderId = 'amazon';
+
+  async fetchLatestVersionInfo(): Promise<StoreLookupResult> {
+    throw new UnsupportedStoreException({
+      message:
+        'Amazon Appstore provider is not yet implemented — see Prompt 11 in the design series',
+    });
+  }
+}

package/src/data/providers/apple/AppleStoreProvider.ts

@@ -0,0 +1,94 @@
+import {
+  AppNotFoundException,
+  RateLimitException,
+  StoreResponseParseException,
+} from '../../../domain/errors/VersionManagerException';
+import type { StoreProviderId } from '../../../domain/models/PlatformId';
+import type {
+  StoreLookupRequest,
+  StoreLookupResult,
+} from '../../../domain/models/StoreLookup';
+import type { IHttpClient } from '../../../domain/ports/IPlatformBridge';
+import type { IStoreProvider } from '../../../domain/ports/IStoreProvider';
+
+interface AppleLookupResult {
+  version: string;
+  trackViewUrl: string;
+  releaseNotes?: string;
+  minimumOsVersion?: string;
+}
+
+interface AppleLookupResponse {
+  resultCount: number;
+  results: AppleLookupResult[];
+}
+
+/**
+ * Real implementation against the public iTunes Lookup API (Prompt 10). Accepts either
+ * the numeric App Store Connect id (`id=`) or, when the app developer doesn't want to
+ * hardcode one, falls back to looking the app up by its own bundle id (`bundleId=`) —
+ * the iTunes Lookup API supports both query params equivalently.
+ */
+export class AppleStoreProvider implements IStoreProvider {
+  readonly id: StoreProviderId = 'apple';
+
+  constructor(
+    private readonly http: IHttpClient,
+    private readonly appStoreId?: string,
+    private readonly region: string = 'us'
+  ) {}
+
+  async fetchLatestVersionInfo(
+    request: StoreLookupRequest
+  ): Promise<StoreLookupResult> {
+    const country = request.region ?? this.region;
+    const identifierParam = this.appStoreId
+      ? `id=${encodeURIComponent(this.appStoreId)}`
+      : `bundleId=${encodeURIComponent(request.bundleId)}`;
+    const url = `https://itunes.apple.com/lookup?${identifierParam}&country=${encodeURIComponent(country)}`;
+    const response = await this.http.request({
+      url,
+      method: 'GET',
+      timeoutMs: request.timeoutMs,
+    });
+
+    const identifier = this.appStoreId ?? request.bundleId;
+
+    if (response.status === 429) {
+      throw new RateLimitException({
+        message: 'Apple iTunes Lookup API rate limit exceeded (HTTP 429)',
+      });
+    }
+    if (response.status !== 200) {
+      throw new AppNotFoundException({
+        message: `Apple iTunes Lookup API returned HTTP ${response.status}`,
+        metadata: { identifier, status: response.status },
+      });
+    }
+
+    let payload: AppleLookupResponse;
+    try {
+      payload = JSON.parse(response.body) as AppleLookupResponse;
+    } catch (error) {
+      throw new StoreResponseParseException({
+        message: 'Apple iTunes Lookup API returned malformed JSON',
+        cause: error,
+      });
+    }
+
+    const result = payload.results[0];
+    if (!result) {
+      throw new AppNotFoundException({
+        message: `No app found in the App Store for "${identifier}"`,
+        metadata: { identifier },
+      });
+    }
+
+    return {
+      latestVersion: result.version,
+      storeUrl: result.trackViewUrl,
+      releaseNotes: result.releaseNotes ?? null,
+      minimumOsVersion: result.minimumOsVersion ?? null,
+    };
+  }
+}

package/src/data/providers/custom-api/CustomApiProvider.ts

@@ -0,0 +1,75 @@
+import {
+  StorePermissionException,
+  StoreResponseParseException,
+} from '../../../domain/errors/VersionManagerException';
+import type { StoreProviderId } from '../../../domain/models/PlatformId';
+import type {
+  StoreLookupRequest,
+  StoreLookupResult,
+} from '../../../domain/models/StoreLookup';
+import type { IHttpClient } from '../../../domain/ports/IPlatformBridge';
+import type { IStoreProvider } from '../../../domain/ports/IStoreProvider';
+
+interface CustomApiResponsePayload {
+  latestVersion?: string;
+  storeUrl?: string;
+  releaseNotes?: string;
+  minimumOsVersion?: string;
+}
+
+/** Generic enterprise/private-distribution provider (Prompt 12). */
+export class CustomApiProvider implements IStoreProvider {
+  readonly id: StoreProviderId = 'custom';
+
+  constructor(
+    private readonly http: IHttpClient,
+    private readonly url: string,
+    private readonly headers: Readonly<Record<string, string>> = {}
+  ) {}
+
+  async fetchLatestVersionInfo(
+    request: StoreLookupRequest
+  ): Promise<StoreLookupResult> {
+    const response = await this.http.request({
+      url: this.url,
+      method: 'GET',
+      headers: this.headers,
+      timeoutMs: request.timeoutMs,
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      throw new StorePermissionException({
+        message: `Custom API rejected the request (HTTP ${response.status})`,
+      });
+    }
+    if (response.status !== 200) {
+      throw new StoreResponseParseException({
+        message: `Custom API returned HTTP ${response.status}`,
+      });
+    }
+
+    let payload: CustomApiResponsePayload;
+    try {
+      payload = JSON.parse(response.body) as CustomApiResponsePayload;
+    } catch (error) {
+      throw new StoreResponseParseException({
+        message: 'Custom API returned malformed JSON',
+        cause: error,
+      });
+    }
+
+    if (!payload.latestVersion || !payload.storeUrl) {
+      throw new StoreResponseParseException({
+        message:
+          'Custom API response is missing required fields "latestVersion"/"storeUrl"',
+      });
+    }
+
+    return {
+      latestVersion: payload.latestVersion,
+      storeUrl: payload.storeUrl,
+      releaseNotes: payload.releaseNotes ?? null,
+      minimumOsVersion: payload.minimumOsVersion ?? null,
+    };
+  }
+}

package/src/data/providers/firebase-remote-config/FirebaseRemoteConfigProvider.ts

@@ -0,0 +1,16 @@
+import { UnsupportedStoreException } from '../../../domain/errors/VersionManagerException';
+import type { StoreProviderId } from '../../../domain/models/PlatformId';
+import type { StoreLookupResult } from '../../../domain/models/StoreLookup';
+import type { IStoreProvider } from '../../../domain/ports/IStoreProvider';
+
+/** Not yet implemented — see Prompt 13 in the design series. */
+export class FirebaseRemoteConfigProvider implements IStoreProvider {
+  readonly id: StoreProviderId = 'firebase-remote-config';
+
+  async fetchLatestVersionInfo(): Promise<StoreLookupResult> {
+    throw new UnsupportedStoreException({
+      message:
+        'Firebase Remote Config provider is not yet implemented — see Prompt 13 in the design series',
+    });
+  }
+}

package/src/data/providers/google-play/GooglePlayProvider.ts

@@ -0,0 +1,75 @@
+import {
+  AppNotFoundException,
+  StoreResponseParseException,
+} from '../../../domain/errors/VersionManagerException';
+import type { StoreProviderId } from '../../../domain/models/PlatformId';
+import type {
+  StoreLookupRequest,
+  StoreLookupResult,
+} from '../../../domain/models/StoreLookup';
+import type { IHttpClient } from '../../../domain/ports/IPlatformBridge';
+import type { IStoreProvider } from '../../../domain/ports/IStoreProvider';
+
+/**
+ * Google Play has no public, unauthenticated lookup API (Prompt 10). This provider is a
+ * best-effort parser of the public store listing page's inline JSON blob. It is
+ * inherently fragile — Play Store markup can change without notice — and is offered as
+ * a pragmatic default; production deployments with a Google Play Developer API service
+ * account should prefer a IStoreProvider backed by that authenticated API instead.
+ *
+ * packageName is optional — on Android the app's own bundle id *is* its package name,
+ * so when it's not supplied explicitly this falls back to request.bundleId.
+ */
+export class GooglePlayProvider implements IStoreProvider {
+  readonly id: StoreProviderId = 'google-play';
+
+  constructor(
+    private readonly http: IHttpClient,
+    private readonly packageName?: string
+  ) {}
+
+  async fetchLatestVersionInfo(
+    request: StoreLookupRequest
+  ): Promise<StoreLookupResult> {
+    const packageName = this.packageName ?? request.bundleId;
+    const storeUrl = `https://play.google.com/store/apps/details?id=${encodeURIComponent(packageName)}&hl=en`;
+    const response = await this.http.request({
+      url: storeUrl,
+      method: 'GET',
+      timeoutMs: request.timeoutMs,
+    });
+
+    if (response.status === 404) {
+      throw new AppNotFoundException({
+        message: `No app found on Google Play for package "${packageName}"`,
+        metadata: { packageName },
+      });
+    }
+    if (response.status !== 200) {
+      throw new StoreResponseParseException({
+        message: `Google Play returned HTTP ${response.status}`,
+      });
+    }
+
+    const version = extractPlayStoreVersion(response.body);
+    if (!version) {
+      throw new StoreResponseParseException({
+        message:
+          'Could not extract a version string from the Google Play store page',
+        metadata: { packageName },
+      });
+    }
+
+    return {
+      latestVersion: version,
+      storeUrl: `https://play.google.com/store/apps/details?id=${packageName}`,
+      releaseNotes: null,
+      minimumOsVersion: null,
+    };
+  }
+}
+
+function extractPlayStoreVersion(html: string): string | null {
+  const match = /\[\[\["(\d+(?:\.\d+){1,3})"\]\]/.exec(html);
+  return match?.[1] ?? null;
+}

package/src/data/providers/huawei/HuaweiAppGalleryProvider.ts

@@ -0,0 +1,21 @@
+import { UnsupportedStoreException } from '../../../domain/errors/VersionManagerException';
+import type { StoreProviderId } from '../../../domain/models/PlatformId';
+import type { StoreLookupResult } from '../../../domain/models/StoreLookup';
+import type { IStoreProvider } from '../../../domain/ports/IStoreProvider';
+
+/**
+ * Not yet implemented — Huawei AppGallery integration is designed in Prompt 11 of this
+ * series (AG Connect API parameters, error-code mapping) but not built in this pass.
+ * The file exists so the provider is independently importable/tree-shakeable
+ * (Prompt 1 §8) without pulling in Apple/Google/Custom code.
+ */
+export class HuaweiAppGalleryProvider implements IStoreProvider {
+  readonly id: StoreProviderId = 'huawei';
+
+  async fetchLatestVersionInfo(): Promise<StoreLookupResult> {
+    throw new UnsupportedStoreException({
+      message:
+        'Huawei AppGallery provider is not yet implemented — see Prompt 11 in the design series',
+    });
+  }
+}

package/src/data/repositories/VersionRepositoryImpl.ts

@@ -0,0 +1,90 @@
+import {
+  toVersionManagerException,
+  UnsupportedStoreException,
+} from '../../domain/errors/VersionManagerException';
+import type {
+  RemoteVersionInfo,
+  UserVersionDecision,
+  VersionCheckRequest,
+} from '../../domain/models/RemoteVersionInfo';
+import type { ICacheStore } from '../../domain/ports/ICacheStore';
+import type { IClock } from '../../domain/ports/IClock';
+import type { IKeyValueStorage } from '../../domain/ports/IPlatformBridge';
+import type { IStoreProvider } from '../../domain/ports/IStoreProvider';
+import type { IVersionRepository } from '../../domain/ports/IVersionRepository';
+
+const REMOTE_INFO_CACHE_KEY = 'remote-version-info';
+const USER_DECISION_STORAGE_KEY = 'vm_user_decision';
+
+/**
+ * Sequential fallback across registered providers (Prompt 14's simpler tier): the first
+ * provider to succeed wins. Only providers the host app actually registers via DI
+ * reach this list — nothing here imports a provider it doesn't need (Prompt 1 §8).
+ */
+export class VersionRepositoryImpl implements IVersionRepository {
+  constructor(
+    private readonly providers: readonly IStoreProvider[],
+    private readonly cache: ICacheStore<RemoteVersionInfo>,
+    private readonly storage: IKeyValueStorage,
+    private readonly clock: IClock
+  ) {}
+
+  async getRemoteVersionInfo(
+    request: VersionCheckRequest
+  ): Promise<RemoteVersionInfo> {
+    if (!request.bypassCache) {
+      const cached = await this.cache.get(REMOTE_INFO_CACHE_KEY);
+      if (cached) return cached;
+    }
+
+    if (this.providers.length === 0) {
+      throw new UnsupportedStoreException({
+        message:
+          'No store providers are registered — configure() must include at least one of stores.ios/.android/.custom/etc',
+      });
+    }
+
+    let lastError: unknown = null;
+    for (const provider of this.providers) {
+      try {
+        const result = await provider.fetchLatestVersionInfo({
+          bundleId: request.bundleId,
+          region: null,
+          timeoutMs: request.timeoutMs,
+        });
+        const info: RemoteVersionInfo = {
+          latestVersion: result.latestVersion,
+          storeUrl: result.storeUrl,
+          releaseNotes: result.releaseNotes,
+          minimumOsVersion: result.minimumOsVersion,
+          fetchedAt: this.clock.now(),
+          provider: provider.id,
+        };
+        await this.cache.set(REMOTE_INFO_CACHE_KEY, info);
+        return info;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw toVersionManagerException(lastError);
+  }
+
+  async getCachedVersionInfo(): Promise<RemoteVersionInfo | null> {
+    return this.cache.get(REMOTE_INFO_CACHE_KEY);
+  }
+
+  async persistUserDecision(decision: UserVersionDecision): Promise<void> {
+    await this.storage.set(USER_DECISION_STORAGE_KEY, JSON.stringify(decision));
+  }
+
+  async getUserDecision(): Promise<UserVersionDecision | null> {
+    const raw = await this.storage.get(USER_DECISION_STORAGE_KEY);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as UserVersionDecision;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/di/container.ts

@@ -0,0 +1,128 @@
+import { PersistentCacheStore } from '../data/cache/PersistentCacheStore';
+import { MemoryCacheStore } from '../data/cache/MemoryCacheStore';
+import { ConfigCache } from '../data/config/ConfigCache';
+import { ConfigDocumentValidator } from '../data/config/ConfigDocumentValidator';
+import { resolveConfigSync } from '../data/config/ConfigLoader';
+import { ConfigProvider } from '../data/config/ConfigProvider';
+import { SignatureVerifier } from '../data/config/SignatureVerifier';
+import { EnvironmentOverrideSource } from '../data/config/sources/EnvironmentOverrideSource';
+import { LocalConfigSource } from '../data/config/sources/LocalConfigSource';
+import { RemoteConfigSource } from '../data/config/sources/RemoteConfigSource';
+import { AppleStoreProvider } from '../data/providers/apple/AppleStoreProvider';
+import { CustomApiProvider } from '../data/providers/custom-api/CustomApiProvider';
+import { GooglePlayProvider } from '../data/providers/google-play/GooglePlayProvider';
+import { VersionRepositoryImpl } from '../data/repositories/VersionRepositoryImpl';
+import { DecisionEngine } from '../domain/engines/decision/DecisionEngine';
+import { PolicyEngine } from '../domain/engines/policy/PolicyEngine';
+import { SemVerEngine } from '../domain/engines/semver/SemVerEngine';
+import type { VersionManagerEventMap } from '../domain/models/Events';
+import type { RemoteVersionInfo } from '../domain/models/RemoteVersionInfo';
+import type {
+  ResolvedVersionManagerConfig,
+  VersionManagerOptions,
+} from '../domain/models/VersionManagerOptions';
+import type { IPlatformBridge } from '../domain/ports/IPlatformBridge';
+import type { IStoreProvider } from '../domain/ports/IStoreProvider';
+import { VersionManagerCore } from '../domain/VersionManagerCore';
+import type { IVersionManagerCore } from '../domain/IVersionManagerCore';
+import { createPlatformBridge } from '../platform/createPlatformBridge';
+import { EventBus } from '../shared/eventbus/EventBus';
+
+/**
+ * Composition root (Prompt 1 §1.3) — the only file in the codebase that imports both a
+ * port and its concrete adapter simultaneously. Only Apple/Google Play/Custom API
+ * providers are wired here; Huawei/Amazon/Firebase Remote Config providers exist as
+ * independently importable files (Prompt 1 §8) but are intentionally not referenced
+ * from this file yet since their implementations are still stubs (see those files'
+ * doc comments) — wiring them here would defeat tree-shaking for no behavioral benefit.
+ */
+export function createVersionManagerCore(
+  options: VersionManagerOptions
+): IVersionManagerCore {
+  // Synchronous — throws InvalidConfigException immediately for a bad options bag
+  // (Prompt 2 §1.3's fail-fast requirement), before any adapter is constructed.
+  const config: ResolvedVersionManagerConfig = resolveConfigSync(options);
+
+  const platformBridge: IPlatformBridge =
+    options.platformBridge ?? createPlatformBridge();
+  const clock = platformBridge.clock;
+  const comparator = new SemVerEngine();
+  const policyEngine = new PolicyEngine(comparator);
+  const decisionEngine = new DecisionEngine(clock);
+  const eventBus = new EventBus<VersionManagerEventMap>();
+
+  const providers = buildProviders(config, platformBridge);
+  const remoteInfoCache =
+    config.cache.storage === 'memory'
+      ? new MemoryCacheStore<RemoteVersionInfo>(clock, config.cache.ttlMs)
+      : new PersistentCacheStore<RemoteVersionInfo>(
+          platformBridge.storage,
+          clock,
+          config.cache.ttlMs
+        );
+
+  const repository = new VersionRepositoryImpl(
+    providers,
+    remoteInfoCache,
+    platformBridge.storage,
+    clock
+  );
+
+  const configProvider = new ConfigProvider({
+    local: new LocalConfigSource(options.configSources?.local),
+    remote: new RemoteConfigSource(platformBridge.http),
+    envOverrides: new EnvironmentOverrideSource(
+      options.configSources?.envOverrides
+    ),
+    cache: new ConfigCache(platformBridge.storage),
+    validator: new ConfigDocumentValidator(),
+    signatureVerifier: new SignatureVerifier(platformBridge.crypto),
+    clock,
+  });
+
+  return new VersionManagerCore({
+    config,
+    rawOptions: options,
+    platformBridge,
+    repository,
+    comparator,
+    policyEngine,
+    decisionEngine,
+    eventBus,
+    clock,
+    configProvider,
+  });
+}
+
+function buildProviders(
+  config: ResolvedVersionManagerConfig,
+  bridge: IPlatformBridge
+): IStoreProvider[] {
+  const providers: IStoreProvider[] = [];
+
+  if (bridge.platform === 'ios' && config.stores.ios) {
+    providers.push(
+      new AppleStoreProvider(
+        bridge.http,
+        config.stores.ios.appStoreId,
+        config.stores.ios.region
+      )
+    );
+  }
+  if (bridge.platform === 'android' && config.stores.android) {
+    providers.push(
+      new GooglePlayProvider(bridge.http, config.stores.android.packageName)
+    );
+  }
+  if (config.stores.custom) {
+    providers.push(
+      new CustomApiProvider(
+        bridge.http,
+        config.stores.custom.url,
+        config.stores.custom.headers
+      )
+    );
+  }
+
+  return providers;
+}

package/src/domain/IVersionManagerCore.ts

@@ -0,0 +1,54 @@
+import type { ActionPlan } from './models/ActionPlan';
+import type {
+  StateChangedEvent,
+  UpdateDetectedEvent,
+  UserActionEvent,
+  VersionManagerErrorEvent,
+  VersionManagerEventMap,
+} from './models/Events';
+import type { LifecycleState } from './models/LifecycleState';
+import type {
+  CheckForUpdatesOptions,
+  ForceTriggerOptions,
+  ResetIgnoredVersionsOptions,
+} from './models/PublicApiOptions';
+import type { UpdateInfo } from './models/UpdateInfo';
+import type { Unsubscribe } from './models/Unsubscribe';
+
+/** Public event subscription surface (Prompt 2 §4.2). */
+export interface IVersionManagerEvents {
+  on<K extends keyof VersionManagerEventMap>(
+    event: K,
+    handler: (payload: VersionManagerEventMap[K]) => void
+  ): Unsubscribe;
+  once<K extends keyof VersionManagerEventMap>(
+    event: K,
+    handler: (payload: VersionManagerEventMap[K]) => void
+  ): Unsubscribe;
+  off<K extends keyof VersionManagerEventMap>(
+    event: K,
+    handler: (payload: VersionManagerEventMap[K]) => void
+  ): void;
+
+  onUpdateDetected(handler: (e: UpdateDetectedEvent) => void): Unsubscribe;
+  onUserAction(handler: (e: UserActionEvent) => void): Unsubscribe;
+  onError(handler: (e: VersionManagerErrorEvent) => void): Unsubscribe;
+  onStateChanged(handler: (e: StateChangedEvent) => void): Unsubscribe;
+}
+
+/** The single class Domain exposes outward (Prompt 1 §3; full spec in Prompt 2). */
+export interface IVersionManagerCore extends IVersionManagerEvents {
+  ready(): Promise<void>;
+
+  checkForUpdates(options?: CheckForUpdatesOptions): Promise<ActionPlan>;
+  forceTriggerUpdate(options?: ForceTriggerOptions): Promise<void>;
+  resetIgnoredVersions(options?: ResetIgnoredVersionsOptions): Promise<void>;
+
+  getCurrentState(): LifecycleState;
+  getUpdateInfo(): UpdateInfo | null;
+  isUpdateAvailable(): boolean;
+  getActionPlan(): ActionPlan | null;
+  getLastCheckedAt(): number | null;
+
+  dispose(): void;
+}