@mpgd/platform 0.14.0 → 0.15.0

package/dist/ads-conformance.d.ts

@@ -0,0 +1,44 @@
+import { adProtocol, adProtocolVersion } from './ads.js';
+export type AdConformanceValue = string | number | boolean | null | readonly AdConformanceValue[] | {
+  readonly [key: string]: AdConformanceValue;
+};
+export type AdConformanceActor = 'game' | 'sdk' | 'backend' | 'clock' | 'runtime';
+export interface AdConformanceStep {
+  readonly actor: AdConformanceActor;
+  readonly action: string;
+  readonly [key: string]: AdConformanceValue;
+}
+export interface AdConformanceVector {
+  readonly vector: string;
+  readonly protocol: typeof adProtocol;
+  readonly version: typeof adProtocolVersion;
+  readonly profile: Readonly<Record<string, AdConformanceValue>>;
+  readonly steps: readonly AdConformanceStep[];
+  readonly expect: Readonly<Record<string, AdConformanceValue>>;
+}
+export interface AdConformanceDriver {
+  /** Complete immediate scheduled work, without waiting for an open native surface. */
+  step(input: AdConformanceStep): Promise<void>;
+  read(): Promise<Readonly<Record<string, AdConformanceValue>>>;
+  dispose(): Promise<void>;
+}
+export interface AdConformanceFixture {
+  readonly name: string;
+  /** A fresh driver for every vector. Expectations are never supplied to the driver. */
+  create(input: {
+    readonly vector: string;
+    readonly profile: Readonly<Record<string, AdConformanceValue>>;
+  }): Promise<AdConformanceDriver>;
+}
+/** Deterministic orchestration only: adapters translate each step into their real SDK input. */
+export declare function runAdConformance(input: {
+  readonly vectors: readonly unknown[];
+  readonly fixtures: readonly AdConformanceFixture[];
+}): Promise<{
+  readonly passed: readonly {
+    readonly fixture: string;
+    readonly vector: string;
+  }[];
+}>;
+/** Clone and freeze the script so fixtures cannot mutate later assertions. */
+export declare function assertAdConformanceVector(value: unknown): AdConformanceVector;

package/dist/ads-conformance.js

@@ -0,0 +1,216 @@
+import { adProtocol, adProtocolVersion } from './ads.js';
+const actions = {
+    game: ['prepare', 'start', 'disposeView'],
+    sdk: ['started', 'rewardEarned', 'closed', 'failed'],
+    backend: ['grant', 'reject'],
+    clock: ['advance'],
+    runtime: ['block', 'release', 'recover', 'restart'],
+};
+const observationKeys = new Set([
+    'sdkShows',
+    'claimRequests',
+    'ledgerGrants',
+    'purchaseUiOpened',
+    'occupied',
+    'outcomes',
+    'claims',
+    'reason',
+    'presentation',
+    'eligibility',
+    'claimState',
+    'preparation',
+    'lateCloseObserved',
+    'updatesAfterViewDisposal',
+    'activeInvocationId',
+    'executionOwners',
+    'reasons',
+    'callerResults',
+    'normalization',
+    'ledgerEntryId',
+]);
+/** Deterministic orchestration only: adapters translate each step into their real SDK input. */
+export async function runAdConformance(input) {
+    if (input.vectors.length === 0 || input.fixtures.length === 0) {
+        throw new TypeError('Ad conformance requires vectors and fixtures.');
+    }
+    const vectors = input.vectors.map(assertAdConformanceVector);
+    assertUnique(vectors.map((vector) => vector.vector), 'vector');
+    assertUnique(input.fixtures.map((fixture) => fixture.name), 'fixture');
+    const passed = [];
+    for (const fixture of input.fixtures) {
+        for (const vector of vectors) {
+            let driver;
+            let failure;
+            let failed = false;
+            try {
+                driver = await fixture.create({ vector: vector.vector, profile: vector.profile });
+                for (const step of vector.steps) {
+                    const { expect: checkpoint, ...action } = step;
+                    await driver.step(action);
+                    if (checkpoint !== undefined) {
+                        assertMatches(cloneValue(await driver.read(), 0), checkpoint, 'checkpoint');
+                    }
+                }
+                const observed = cloneValue(await driver.read(), 0);
+                assertMatches(observed, vector.expect, 'expect');
+            }
+            catch (error) {
+                failed = true;
+                failure = error;
+            }
+            finally {
+                try {
+                    await driver?.dispose();
+                }
+                catch (error) {
+                    if (!failed) {
+                        failed = true;
+                        failure = error;
+                    }
+                }
+            }
+            if (failed) {
+                throw new Error(`Ad conformance failed: ${fixture.name}/${vector.vector}.`, {
+                    cause: failure,
+                });
+            }
+            passed.push(Object.freeze({ fixture: fixture.name, vector: vector.vector }));
+        }
+    }
+    return Object.freeze({ passed: Object.freeze(passed) });
+}
+/** Clone and freeze the script so fixtures cannot mutate later assertions. */
+export function assertAdConformanceVector(value) {
+    const record = asRecord(cloneValue(value, 0));
+    if (typeof record.vector !== 'string' || !/^[a-z][a-z0-9-]{0,127}$/.test(record.vector)
+        || record.protocol !== adProtocol || record.version !== adProtocolVersion) {
+        throw new TypeError('Invalid advertising vector identity or protocol.');
+    }
+    const profile = asRecord(record.profile);
+    if (!Array.isArray(profile.formats) || profile.formats.some((format) => format !== 'rewarded' && format !== 'interstitial')
+        || typeof profile.configured !== 'boolean'
+        || (profile.rewardSignal !== 'immediate' && profile.rewardSignal !== 'delayed')) {
+        throw new TypeError('Invalid advertising vector profile.');
+    }
+    if (!Array.isArray(record.steps) || record.steps.length === 0 || record.steps.length > 500) {
+        throw new TypeError('Invalid advertising vector steps.');
+    }
+    if ((profile.policyEnabled !== undefined && typeof profile.policyEnabled !== 'boolean')
+        || (profile.actionRequired !== undefined && typeof profile.actionRequired !== 'boolean')
+        || (profile.preparation !== undefined && !['ready', 'deferred', 'unavailable', 'failed'].includes(profile.preparation))) {
+        throw new TypeError('Invalid advertising vector policy or preparation.');
+    }
+    for (const supplied of record.steps) {
+        const step = asRecord(supplied);
+        if (typeof step.actor !== 'string' || !Object.hasOwn(actions, step.actor)
+            || typeof step.action !== 'string' || !actions[step.actor].includes(step.action)) {
+            throw new TypeError('Invalid advertising vector actor/action.');
+        }
+        if (['start', 'disposeView', 'started', 'rewardEarned', 'closed', 'failed', 'grant', 'reject', 'recover'].includes(step.action)
+            && (typeof step.invocationId !== 'string' || step.invocationId.trim() === '' || step.invocationId.length > 512)) {
+            throw new TypeError('Invalid advertising step invocation identity.');
+        }
+        if (step.action === 'start' || step.action === 'prepare') {
+            if ((step.format !== 'rewarded' && step.format !== 'interstitial'
+                && !(step.action === 'start' && step.format === 'purchase'))
+                || typeof step.placementId !== 'string' || step.placementId.trim() === '') {
+                throw new TypeError('Invalid advertising step placement.');
+            }
+        }
+        if (step.actor === 'backend' && step.action === 'grant') {
+            for (const field of ['verifiedImpressionId', 'ledgerEntryId']) {
+                const id = step[field];
+                if (typeof id !== 'string' || id.trim() === '' || id.length > 512) {
+                    throw new TypeError('Invalid advertising backend grant identity.');
+                }
+            }
+        }
+        if (step.actor === 'clock' && (!Number.isSafeInteger(step.milliseconds) || step.milliseconds < 0)) {
+            throw new TypeError('Invalid advertising clock advance.');
+        }
+        if ((step.action === 'block' || step.action === 'release')
+            && (typeof step.owner !== 'string' || step.owner.trim() === '')) {
+            throw new TypeError('Invalid advertising execution owner.');
+        }
+        if (step.expect !== undefined) {
+            assertExpectation(step.expect);
+        }
+    }
+    assertExpectation(record.expect);
+    return record;
+}
+function assertExpectation(value) {
+    const expected = asRecord(value);
+    if (Object.keys(expected).length === 0 || Object.keys(expected).some((key) => !observationKeys.has(key))) {
+        throw new TypeError('Invalid advertising vector expectations.');
+    }
+}
+function assertUnique(names, kind) {
+    const unique = new Set();
+    for (const name of names) {
+        if (typeof name !== 'string' || name.trim() === '' || unique.has(name)) {
+            throw new TypeError(`Invalid or duplicate ad conformance ${kind} name.`);
+        }
+        unique.add(name);
+    }
+}
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('Expected an advertising conformance object.');
+    }
+    return value;
+}
+function cloneValue(value, depth) {
+    if (depth > 12) {
+        throw new TypeError('Advertising conformance value is too deeply nested.');
+    }
+    if (value === null || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'string' && value.length <= 8192) {
+        return value;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (Array.isArray(value) && value.length <= 500) {
+        return Object.freeze(value.map((entry) => cloneValue(entry, depth + 1)));
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        const entries = Object.entries(value);
+        if (entries.length <= 128 && entries.every(([key]) => key.length <= 128)) {
+            return Object.freeze(Object.fromEntries(entries.map(([key, entry]) => [key, cloneValue(entry, depth + 1)])));
+        }
+    }
+    throw new TypeError('Invalid advertising conformance value.');
+}
+function assertMatches(actual, expected, path) {
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual) || actual.length !== expected.length) {
+            throw new Error(`Advertising observation differs at ${path}.`);
+        }
+        for (let i = 0; i < expected.length; i += 1) {
+            const wanted = expected[i];
+            const observed = actual[i];
+            if (wanted === undefined || observed === undefined) {
+                throw new Error(`Advertising observation missing at ${path}[${i}].`);
+            }
+            assertMatches(observed, wanted, `${path}[${i}]`);
+        }
+        return;
+    }
+    if (expected !== null && typeof expected === 'object') {
+        const record = asRecord(actual);
+        for (const [key, wanted] of Object.entries(expected)) {
+            const observed = record[key];
+            if (!Object.hasOwn(record, key) || observed === undefined) {
+                throw new Error(`Advertising observation missing at ${path}.${key}.`);
+            }
+            assertMatches(observed, wanted, `${path}.${key}`);
+        }
+        return;
+    }
+    if (actual !== expected) {
+        throw new Error(`Advertising observation differs at ${path}.`);
+    }
+}

package/dist/ads.d.ts

@@ -0,0 +1,93 @@
+import type { AdAdapter, PlatformEvidenceEnvelope } from './index.js';
+export declare const adProtocolVersion: '2.0.0-draft.1';
+export declare const adProtocol: 'mpgd.ads.v2';
+export type AdFormat = 'rewarded' | 'interstitial';
+export type AdProviderId = string;
+export type AdReason = 'unsupported' | 'configuration-required' | 'policy-disabled' | 'action-required' | 'no-fill' | 'busy' | 'transient-failure' | 'outcome-unknown';
+export type AdPresentationState = 'not-started' | 'open' | 'closed' | 'unknown';
+export type AdRewardEligibility = 'eligible' | 'not-earned' | 'unknown' | 'not-applicable';
+export interface AdPlacementInput {
+  readonly placementId: string;
+  readonly format: AdFormat;
+}
+export interface AdShowInput extends AdPlacementInput {
+  readonly invocationId: string;
+  readonly idempotencyKey: string;
+}
+export interface AdAvailability {
+  readonly state: 'available' | 'unsupported' | 'configuration-required' | 'action-required' | 'temporarily-unavailable';
+  readonly reason?: AdReason;
+}
+export interface AdPreparationResult {
+  readonly status: 'ready' | 'deferred' | 'unavailable' | 'failed';
+  readonly reason?: AdReason;
+}
+export interface AdShowResult {
+  readonly providerId: AdProviderId;
+  readonly invocationId: string;
+  readonly format: AdFormat;
+  readonly outcome: 'shown' | 'skipped' | 'unavailable' | 'failed' | 'pending';
+  readonly presentation: Exclude<AdPresentationState, 'open'>;
+  readonly eligibility: AdRewardEligibility;
+  readonly reason?: AdReason;
+  /** A callback is a claim candidate only; no ledger grant belongs here. */
+  readonly evidence?: PlatformEvidenceEnvelope;
+  /** Server proof-lookup correlation; it does not establish local reward eligibility. */
+  readonly claimEvidence?: PlatformEvidenceEnvelope;
+}
+export type AdPresentationEvent = Readonly<{
+  providerId: AdProviderId;
+  invocationId: string;
+  sequence: number;
+} & ({
+  type: 'requested';
+  claimEvidence?: PlatformEvidenceEnvelope;
+} | {
+  type: 'started' | 'closed' | 'unknown';
+} | {
+  type: 'reward-earned';
+  evidence: PlatformEvidenceEnvelope;
+} | {
+  type: 'failed';
+  reason: AdReason;
+})>;
+/** Provider-facing surface. Runtime arbitration and backend grants are separate owners. */
+export interface AdProvider {
+  readonly id: AdProviderId;
+  readonly protocol: typeof adProtocol;
+  readonly protocolVersion: typeof adProtocolVersion;
+  readonly rewardSignal: 'immediate' | 'delayed';
+  getAvailability(input: AdPlacementInput): Promise<AdAvailability>;
+  preload(input: AdPlacementInput): Promise<AdPreparationResult>;
+  show(input: AdShowInput): Promise<AdShowResult>;
+  /** Install before show; unknown presentation must retain a later close observer. */
+  subscribe(listener: (event: AdPresentationEvent) => void): () => void;
+}
+export interface AdSessionSnapshot {
+  readonly providerId: AdProviderId;
+  readonly invocationId: string;
+  readonly format: AdFormat;
+  readonly rewardSignal: 'immediate' | 'delayed';
+  readonly sequence: number;
+  readonly presentation: AdPresentationState;
+  readonly eligibility: AdRewardEligibility;
+  readonly started: boolean;
+  readonly terminal: boolean;
+  readonly reason?: AdReason;
+  readonly evidence?: PlatformEvidenceEnvelope;
+  readonly claimEvidence?: PlatformEvidenceEnvelope;
+}
+export declare function createAdSession(input: {
+  readonly providerId: AdProviderId;
+  readonly invocationId: string;
+  readonly format: AdFormat;
+  readonly rewardSignal?: 'immediate' | 'delayed';
+}): AdSessionSnapshot;
+/** Pure transition: stale identities, duplicate events, and late reopen signals are ignored. */
+export declare function reduceAdSession(snapshot: AdSessionSnapshot, supplied: AdPresentationEvent): AdSessionSnapshot;
+export declare function assertAdShowInput(value: unknown): AdShowInput;
+export declare function assertAdAvailability(value: unknown): AdAvailability;
+export declare function assertAdPreparationResult(value: unknown): AdPreparationResult;
+export declare function assertAdPresentationEvent(value: unknown): AdPresentationEvent;
+export declare function assertAdShowResult(value: unknown): AdShowResult;
+export declare function toAdAdapter(provider: AdProvider): AdAdapter;

package/dist/ads.js

@@ -0,0 +1,306 @@
+export const adProtocolVersion = '2.0.0-draft.1';
+export const adProtocol = 'mpgd.ads.v2';
+export function createAdSession(input) {
+    assertId(input.providerId, 'providerId');
+    assertId(input.invocationId, 'invocationId');
+    assertFormat(input.format);
+    if (input.rewardSignal !== undefined && input.rewardSignal !== 'immediate' && input.rewardSignal !== 'delayed') {
+        throw new TypeError('Invalid ad reward signal.');
+    }
+    return Object.freeze({
+        providerId: input.providerId,
+        invocationId: input.invocationId,
+        format: input.format,
+        rewardSignal: input.rewardSignal ?? 'immediate',
+        sequence: 0,
+        presentation: 'not-started',
+        eligibility: input.format === 'interstitial' ? 'not-applicable' : 'unknown',
+        started: false,
+        terminal: false,
+    });
+}
+/** Pure transition: stale identities, duplicate events, and late reopen signals are ignored. */
+export function reduceAdSession(snapshot, supplied) {
+    const header = assertRecord(supplied);
+    assertId(header.providerId, 'providerId');
+    assertId(header.invocationId, 'invocationId');
+    if (header.providerId !== snapshot.providerId || header.invocationId !== snapshot.invocationId) {
+        return snapshot;
+    }
+    if (!Number.isSafeInteger(header.sequence) || header.sequence < 1) {
+        throw new TypeError('Invalid ad event sequence.');
+    }
+    if (header.sequence <= snapshot.sequence) {
+        return snapshot;
+    }
+    const event = assertAdPresentationEvent(supplied);
+    const next = { ...snapshot, sequence: event.sequence };
+    // A closed invocation may receive delayed reward evidence, but cannot reopen.
+    if (snapshot.terminal && (event.type !== 'reward-earned'
+        || snapshot.presentation !== 'closed' || snapshot.rewardSignal !== 'delayed')) {
+        return Object.freeze(next);
+    }
+    switch (event.type) {
+        case 'requested':
+            return Object.freeze({ ...next, ...(snapshot.format !== 'rewarded' || event.claimEvidence === undefined
+                    ? {} : { claimEvidence: snapshot.claimEvidence ?? event.claimEvidence }) });
+        case 'started':
+            return Object.freeze({ ...next, presentation: 'open', started: true });
+        case 'reward-earned':
+            if (snapshot.format !== 'rewarded' || snapshot.eligibility === 'eligible') {
+                return Object.freeze(next);
+            }
+            return Object.freeze({ ...next, eligibility: 'eligible', evidence: event.evidence });
+        case 'unknown':
+            return Object.freeze({ ...next, presentation: 'unknown', reason: 'outcome-unknown' });
+        case 'closed': {
+            const { reason: previousReason, claimEvidence, ...closed } = next;
+            let eligibility = snapshot.eligibility;
+            if (snapshot.format === 'interstitial') {
+                eligibility = 'not-applicable';
+            }
+            else if (eligibility !== 'eligible') {
+                eligibility = snapshot.rewardSignal === 'delayed' ? 'unknown' : 'not-earned';
+            }
+            return Object.freeze({
+                ...closed,
+                presentation: 'closed',
+                terminal: true,
+                ...(previousReason === undefined || previousReason === 'outcome-unknown' ? {} : { reason: previousReason }),
+                eligibility,
+                ...(claimEvidence === undefined || eligibility === 'not-earned' || eligibility === 'not-applicable'
+                    ? {} : { claimEvidence }),
+            });
+        }
+        case 'failed': {
+            const { claimEvidence, ...failed } = next;
+            return Object.freeze({
+                ...failed,
+                presentation: snapshot.started ? 'closed' : 'not-started',
+                terminal: true,
+                reason: event.reason,
+                ...(snapshot.started && claimEvidence !== undefined ? { claimEvidence } : {}),
+            });
+        }
+    }
+}
+export function assertAdShowInput(value) {
+    const record = assertRecord(value);
+    assertId(record.placementId, 'placementId');
+    assertId(record.invocationId, 'invocationId');
+    assertId(record.idempotencyKey, 'idempotencyKey');
+    assertFormat(record.format);
+    return Object.freeze({
+        placementId: record.placementId,
+        invocationId: record.invocationId,
+        idempotencyKey: record.idempotencyKey,
+        format: record.format,
+    });
+}
+export function assertAdAvailability(value) {
+    const record = assertRecord(value);
+    if (!['available', 'unsupported', 'configuration-required', 'action-required', 'temporarily-unavailable'].includes(record.state)) {
+        throw new TypeError('Invalid ad availability.');
+    }
+    if (record.reason !== undefined) {
+        assertReason(record.reason);
+        if (record.state === 'available') {
+            throw new TypeError('Available advertising cannot carry an unavailable reason.');
+        }
+    }
+    return Object.freeze({
+        state: record.state,
+        ...(record.reason === undefined ? {} : { reason: record.reason }),
+    });
+}
+export function assertAdPreparationResult(value) {
+    const record = assertRecord(value);
+    if (!['ready', 'deferred', 'unavailable', 'failed'].includes(record.status)) {
+        throw new TypeError('Invalid ad preparation result.');
+    }
+    if (record.reason !== undefined) {
+        assertReason(record.reason);
+        if (record.status === 'ready' || record.status === 'deferred') {
+            throw new TypeError('Successful advertising preparation cannot carry a failure reason.');
+        }
+    }
+    return Object.freeze({
+        status: record.status,
+        ...(record.reason === undefined ? {} : { reason: record.reason }),
+    });
+}
+export function assertAdPresentationEvent(value) {
+    const record = assertRecord(value);
+    assertId(record.providerId, 'providerId');
+    assertId(record.invocationId, 'invocationId');
+    if (!Number.isSafeInteger(record.sequence) || record.sequence < 1) {
+        throw new TypeError('Invalid ad event sequence.');
+    }
+    const base = {
+        providerId: record.providerId,
+        invocationId: record.invocationId,
+        sequence: record.sequence,
+    };
+    switch (record.type) {
+        case 'requested':
+            return Object.freeze({ ...base, type: 'requested', ...(record.claimEvidence === undefined
+                    ? {} : { claimEvidence: assertEvidence(record.claimEvidence) }) });
+        case 'started':
+        case 'closed':
+        case 'unknown':
+            return Object.freeze({ ...base, type: record.type });
+        case 'failed':
+            assertReason(record.reason);
+            return Object.freeze({ ...base, type: 'failed', reason: record.reason });
+        case 'reward-earned':
+            return Object.freeze({
+                ...base,
+                type: 'reward-earned',
+                evidence: assertEvidence(record.evidence),
+            });
+        default:
+            throw new TypeError('Invalid ad event type.');
+    }
+}
+export function assertAdShowResult(value) {
+    const record = assertRecord(value);
+    assertId(record.providerId, 'providerId');
+    assertId(record.invocationId, 'invocationId');
+    assertFormat(record.format);
+    if (!['shown', 'skipped', 'unavailable', 'failed', 'pending'].includes(record.outcome)
+        || !['not-started', 'closed', 'unknown'].includes(record.presentation)
+        || !['eligible', 'not-earned', 'unknown', 'not-applicable'].includes(record.eligibility)) {
+        throw new TypeError('Invalid ad result state.');
+    }
+    if (record.reason !== undefined) {
+        assertReason(record.reason);
+    }
+    if ((record.format === 'interstitial') !== (record.eligibility === 'not-applicable')
+        || ((record.outcome === 'shown' || record.outcome === 'skipped') && record.presentation !== 'closed')
+        || (record.presentation === 'unknown' && record.outcome !== 'pending')
+        || (record.outcome === 'pending' && record.presentation !== 'unknown')
+        || (record.outcome === 'unavailable' && record.presentation !== 'not-started')
+        || (record.eligibility === 'eligible' && record.presentation === 'not-started')
+        || (record.outcome === 'skipped' && record.eligibility === 'eligible')
+        || (record.presentation === 'unknown' && record.reason !== 'outcome-unknown')
+        || (record.eligibility === 'eligible' && record.evidence === undefined)
+        || (record.evidence !== undefined && record.eligibility !== 'eligible')) {
+        throw new TypeError('Inconsistent ad result state.');
+    }
+    if (record.claimEvidence !== undefined && (record.format !== 'rewarded'
+        || record.presentation === 'not-started'
+        || record.eligibility === 'not-earned' || record.eligibility === 'not-applicable')) {
+        throw new TypeError('Inconsistent ad claim candidate state.');
+    }
+    return Object.freeze({
+        providerId: record.providerId,
+        invocationId: record.invocationId,
+        format: record.format,
+        outcome: record.outcome,
+        presentation: record.presentation,
+        eligibility: record.eligibility,
+        ...(record.reason === undefined ? {} : { reason: record.reason }),
+        ...(record.evidence === undefined ? {} : { evidence: assertEvidence(record.evidence) }),
+        ...(record.claimEvidence === undefined ? {} : { claimEvidence: assertEvidence(record.claimEvidence) }),
+    });
+}
+/** Additive v1 facade. It never reports an SDK eligibility event as a grant. */
+let legacyInterstitialSequence = 0;
+export function toAdAdapter(provider) {
+    // These ids identify impressions, not authorization. A per-facade nonce survives
+    // resettable module counters without requiring DOM/SDK/crypto globals.
+    const interstitialSessionId = [
+        Date.now().toString(36), Math.random().toString(36).slice(2), Math.random().toString(36).slice(2),
+    ].join('-');
+    assertId(provider.id, 'providerId');
+    if (provider.protocol !== adProtocol || provider.protocolVersion !== adProtocolVersion) {
+        throw new TypeError('Unsupported advertising provider protocol.');
+    }
+    if (provider.rewardSignal !== 'immediate' && provider.rewardSignal !== 'delayed') {
+        throw new TypeError('Invalid advertising provider reward signal.');
+    }
+    return {
+        provider,
+        async preload(input) {
+            if (input.format === 'banner') {
+                return;
+            }
+            assertAdPreparationResult(await provider.preload({ placementId: input.placementId, format: input.format ?? 'rewarded' }));
+        },
+        async showRewarded(input) {
+            const result = assertAdShowResult(await provider.show({
+                ...input, format: 'rewarded', invocationId: input.idempotencyKey,
+            }));
+            if (result.format !== 'rewarded' || result.providerId !== provider.id || result.invocationId !== input.idempotencyKey) {
+                throw new TypeError('Ad result does not match its invocation.');
+            }
+            let status;
+            if (result.eligibility === 'eligible') {
+                status = result.presentation === 'unknown' ? 'pending' : 'completed';
+            }
+            else if (result.outcome === 'shown') {
+                status = result.eligibility === 'unknown' ? 'pending' : 'skipped';
+            }
+            else {
+                status = result.outcome;
+            }
+            const evidence = result.claimEvidence ?? result.evidence;
+            return { status, rewardGranted: false, ...(evidence === undefined ? {} : { evidence }) };
+        },
+        async showInterstitial(input) {
+            const invocationId = `legacy-interstitial:${interstitialSessionId}:${++legacyInterstitialSequence}`;
+            const result = assertAdShowResult(await provider.show({
+                ...input, format: 'interstitial', invocationId, idempotencyKey: invocationId,
+            }));
+            if (result.format !== 'interstitial' || result.providerId !== provider.id || result.invocationId !== invocationId) {
+                throw new TypeError('Ad result does not match its invocation.');
+            }
+            let status = 'skipped';
+            if (result.outcome === 'shown') {
+                status = 'shown';
+            }
+            else if (result.outcome === 'unavailable') {
+                status = 'unavailable';
+            }
+            return { status };
+        },
+    };
+}
+function assertRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('Expected an ad contract object.');
+    }
+    return value;
+}
+function assertId(value, name) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 512) {
+        throw new TypeError(`Invalid ad ${name}.`);
+    }
+}
+function assertFormat(value) {
+    if (value !== 'rewarded' && value !== 'interstitial') {
+        throw new TypeError('Invalid ad format.');
+    }
+}
+function assertReason(value) {
+    if (!['unsupported', 'configuration-required', 'policy-disabled', 'action-required',
+        'no-fill', 'busy', 'transient-failure', 'outcome-unknown'].includes(value)) {
+        throw new TypeError('Invalid ad reason.');
+    }
+}
+function assertEvidence(value) {
+    const record = assertRecord(value);
+    assertId(record.schema, 'evidence schema');
+    const payload = assertRecord(record.payload);
+    const entries = Object.entries(payload);
+    if (entries.length > 32 || entries.some(([key, item]) => key.length > 128
+        || (typeof item !== 'string' && typeof item !== 'number' && typeof item !== 'boolean')
+        || (typeof item === 'string' && item.length > 4096)
+        || (typeof item === 'number' && !Number.isFinite(item)))) {
+        throw new TypeError('Invalid ad evidence payload.');
+    }
+    return Object.freeze({
+        schema: record.schema,
+        payload: Object.freeze(Object.fromEntries(entries)),
+    });
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { AdProvider } from './ads.js';
 export type PlatformTarget = 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8' | 'telegram' | 'tauri' | 'wechat' | 'tiktok';
 export type StarterLogicalProductId = 'COINS_100' | 'COINS_500' | 'REMOVE_ADS';
 export type LogicalProductId = StarterLogicalProductId | (string & Record<never, never>);
@@ -112,6 +113,8 @@ export interface CommerceAdapter {
   getEntitlements(): Promise<readonly Entitlement[]>;
 }
 export interface AdAdapter {
+  /** Optional versioned provider surface; v1 methods remain compatible. */
+  readonly provider?: AdProvider;
   preload(input: {
     readonly placementId: LogicalAdPlacementId;
     /** Allows a shared provider preload method to enforce format readiness. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/platform",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Shared platform gateway, monetization, ads, leaderboard, identity, lifecycle, and storage contracts for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,14 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "./ads": {
+      "types": "./dist/ads.d.ts",
+      "default": "./dist/ads.js"
+    },
+    "./ads-conformance": {
+      "types": "./dist/ads-conformance.d.ts",
+      "default": "./dist/ads-conformance.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
@@ -56,6 +64,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "vitest run && node test/capability-conformance-dist-import.mjs && node test/storage-conformance-dist-import.mjs"
+    "test": "vitest run && node test/capability-conformance-dist-import.mjs && node test/storage-conformance-dist-import.mjs && node test/ads-dist-import.mjs"
   }
 }