@mpgd/platform 0.21.0 → 0.23.0

package/dist/capability-conformance.d.ts

@@ -1,6 +1,6 @@
 import type { PlatformCapabilities, PlatformGateway, PlatformTarget } from './index.js';
-export declare const platformCapabilityKeys: readonly ["nativeIap", "nativeAds", "rewardedAds", "interstitialAds", "nativeLeaderboard", "remoteLeaderboard", "achievements", "cloudSave", "socialShare", "haptics", "localizedContent"];
-export declare const optionalPlatformCapabilityKeys: readonly ["bannerAds", "subscriptionIap"];
+export declare const platformCapabilityKeys: readonly ["nativeAds", "rewardedAds", "interstitialAds", "nativeLeaderboard", "remoteLeaderboard", "achievements", "cloudSave", "socialShare", "haptics", "localizedContent"];
+export declare const optionalPlatformCapabilityKeys: readonly ["bannerAds"];
 export interface PlatformGatewayCapabilityConformanceTransition {
   readonly update: () => Promise<void> | void;
   readonly expectedCapabilities: PlatformCapabilities;
@@ -24,10 +24,11 @@ export interface PlatformGatewayCapabilityConformanceReport {
 }
 /**
 * Runs provider-neutral capability checks against real adapter gateways or
-* target-configured wrappers. Every read must return a complete boolean
-* snapshot, a fresh object, and the provider's latest state.
+* target-configured wrappers. Every read must return every required boolean
+* key, known readiness states, the commerce and notifications blocks under
+* their own rules, a fresh object, and the provider's latest state.
 * @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
-* @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #a1834db Reviewed required booleans, optional banner/subscription defaults, ordered readiness comparison, and fresh nested rereads.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #12e3a3a Reviewed required booleans, the required commerce block, the optional banner default, ordered readiness comparison, and fresh nested rereads, including notification identity and dense purpose checks.
 * @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
 * @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
 * @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.

package/dist/capability-conformance.js

@@ -1,6 +1,4 @@
-import { deriveLegacyCommerceCapabilities } from './commerce-capabilities.js';
 export const platformCapabilityKeys = Object.freeze([
-    'nativeIap',
     'nativeAds',
     'rewardedAds',
     'interstitialAds',
@@ -14,7 +12,6 @@ export const platformCapabilityKeys = Object.freeze([
 ]);
 export const optionalPlatformCapabilityKeys = Object.freeze([
     'bannerAds',
-    'subscriptionIap',
 ]);
 const allowedPlatformCapabilityKeys = Object.freeze([
     ...platformCapabilityKeys,
@@ -24,11 +21,10 @@ const allowedPlatformCapabilityKeySet = new Set([
     ...allowedPlatformCapabilityKeys,
     'providerAvailability',
     'commerce',
+    'notifications',
 ]);
 const optionalPlatformCapabilityKeySet = new Set(optionalPlatformCapabilityKeys);
 const providerFeatureSet = new Set([
-    'nativeIap',
-    'subscriptionIap',
     'rewardedAds',
     'interstitialAds',
     'bannerAds',
@@ -43,8 +39,8 @@ const providerAvailabilitySet = new Set([
     'temporarily-unavailable',
     'available',
 ]);
-// The optional commerce v2 block follows the same rules as the boolean
-// snapshot: exact keys, typed values, and a fresh object on every read.
+// The commerce block follows the same rules as the boolean snapshot: exact
+// keys, typed values, and a fresh object on every read.
 const commerceCapabilityBlockKeys = Object.freeze({
     purchase: ['consumable', 'durable', 'subscription', 'quantity'],
     catalog: ['products', 'offers', 'localizedPrice'],
@@ -56,12 +52,38 @@ const commerceCapabilityEnums = Object.freeze({
     'authority.evidence': ['client-token', 'host-callback', 'adapter-settled', 'server-push'],
     'authority.accountBinding': ['required', 'optional', 'host'],
 });
+const notificationCapabilityFields = Object.freeze({
+    permission: {
+        scope: { kind: 'enum', values: ['app', 'topic'] },
+        prompt: { kind: 'enum', values: ['os', 'host', 'game'] },
+        readable: { kind: 'boolean' },
+        serverReadable: { kind: 'boolean' },
+        allowance: { kind: 'enum', values: ['persistent', 'per-send'] },
+        userGesture: { kind: 'boolean' },
+        promptLimit: { kind: 'count', optional: true },
+        maxTopicsPerPrompt: { kind: 'count', optional: true },
+        settings: { kind: 'boolean' },
+    },
+    remote: {
+        supported: { kind: 'boolean' },
+        purposes: { kind: 'purposes' },
+        addressing: { kind: 'enum', values: ['device', 'platform-user', 'none'] },
+        content: { kind: 'enum', values: ['free-form', 'host-template'] },
+    },
+    local: {
+        supported: { kind: 'boolean' },
+        maxPending: { kind: 'count', optional: true },
+    },
+});
+const notificationPurposes = ['service', 'requested', 'advertising'];
+const notificationOpenPaths = ['payload', 'landing-url', 'host-link', 'none'];
 /**
  * Runs provider-neutral capability checks against real adapter gateways or
- * target-configured wrappers. Every read must return a complete boolean
- * snapshot, a fresh object, and the provider's latest state.
+ * target-configured wrappers. Every read must return every required boolean
+ * key, known readiness states, the commerce and notifications blocks under
+ * their own rules, a fresh object, and the provider's latest state.
  * @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
- * @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #a1834db Reviewed required booleans, optional banner/subscription defaults, ordered readiness comparison, and fresh nested rereads.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #12e3a3a Reviewed required booleans, the required commerce block, the optional banner default, ordered readiness comparison, and fresh nested rereads, including notification identity and dense purpose checks.
  * @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
  * @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
  * @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.
@@ -102,11 +124,12 @@ async function runFixture(fixture) {
         : cloneExpectedCapabilities(fixture.transition.expectedCapabilities);
     assertEqual(fixture.gateway.target, fixture.expectedTarget, 'gateway target must match the fixture target');
     const first = await fixture.gateway.getCapabilities();
-    assertCapabilitySnapshot(first, initialExpected);
+    assertCapabilitySnapshot(first, initialExpected, fixture.gateway);
     tryMutateSnapshot(first);
     const second = await fixture.gateway.getCapabilities();
     assert(second !== first, 'getCapabilities must return a fresh snapshot object for every read');
-    assertCapabilitySnapshot(second, initialExpected);
+    assertCapabilitySnapshot(second, initialExpected, fixture.gateway);
+    assertNotificationSnapshotFreshness(first, second);
     if (fixture.transition === undefined || transitionExpected === undefined) {
         return;
     }
@@ -115,9 +138,23 @@ async function runFixture(fixture) {
     const updated = await fixture.gateway.getCapabilities();
     assert(updated !== second, 'getCapabilities must return a fresh snapshot after a provider transition');
     assert(updated !== first, 'getCapabilities must not reuse an earlier snapshot after a provider transition');
-    assertCapabilitySnapshot(updated, transitionExpected);
+    assertCapabilitySnapshot(updated, transitionExpected, fixture.gateway);
+    assertNotificationSnapshotFreshness(first, updated);
+    assertNotificationSnapshotFreshness(second, updated);
+}
+function assertNotificationSnapshotFreshness(previous, next) {
+    const first = previous.notifications;
+    const second = next.notifications;
+    if (first === undefined || second === undefined) {
+        return;
+    }
+    assert(second !== first, 'notification capabilities must return a fresh block for every read');
+    for (const key of ['permission', 'remote', 'local']) {
+        assert(second[key] !== first[key], `notification capabilities must return a fresh ${key} record`);
+    }
+    assert(second.remote.purposes !== first.remote.purposes, 'notification capabilities must return a fresh purposes list');
 }
-function assertCapabilitySnapshot(actual, expected) {
+function assertCapabilitySnapshot(actual, expected, gateway) {
     const actualKeys = Object.keys(actual).sort();
     const missingKeys = platformCapabilityKeys.filter((key) => !Object.hasOwn(actual, key));
     const unexpectedKeys = actualKeys.filter((key) => !allowedPlatformCapabilityKeySet.has(key));
@@ -132,14 +169,85 @@ function assertCapabilitySnapshot(actual, expected) {
     assertProviderAvailabilityShape(actual.providerAvailability);
     assertEqual(normalizedAvailability(actual.providerAvailability), normalizedAvailability(expected.providerAvailability), 'provider availability must match the expected provider state');
     assertCommerceCapabilityBlock(actual, expected.commerce);
+    assertNotificationCapabilityBlock(actual, expected.notifications, gateway);
 }
-function assertCommerceCapabilityBlock(snapshot, expected) {
-    const actual = snapshot.commerce;
+function assertNotificationCapabilityBlock(snapshot, expected, gateway) {
+    const actual = snapshot.notifications;
+    // The block describes the exposed provider (notifications RFC "Capabilities").
+    assertEqual(actual !== undefined, gateway.notificationsV2 !== undefined, 'notification capabilities must be present exactly when the gateway exposes notificationsV2');
     if (actual === undefined) {
-        assert(expected === undefined, 'commerce capabilities must be present when the fixture expects them');
+        assert(expected === undefined, 'notification capabilities must be present when the fixture expects them');
         return;
     }
-    assert(expected !== undefined, 'commerce capabilities must be absent when the fixture omits them');
+    assert(expected !== undefined, 'notification capabilities must be absent when the fixture omits them');
+    assert(isPlainRecord(actual), 'notification capabilities must be a non-array record');
+    assertEqual(JSON.stringify(Object.keys(actual).sort()), JSON.stringify(['availability', 'local', 'open', 'permission', 'remote']), 'notification capabilities must contain exactly availability, permission, remote, local, and open');
+    for (const [group, fields] of Object.entries(notificationCapabilityFields)) {
+        const nested = actual[group];
+        assert(isPlainRecord(nested), `notification ${group} capabilities must be a non-array record`);
+        const unknownKeys = Object.keys(nested).filter((key) => !Object.hasOwn(fields, key));
+        assertEqual(JSON.stringify(unknownKeys), '[]', `notification ${group} capabilities must contain no unknown keys`);
+        for (const [key, field] of Object.entries(fields)) {
+            const path = `${group}.${key}`;
+            if (!Object.hasOwn(nested, key)) {
+                assert(field.optional === true, `notification capability ${path} is required`);
+                continue;
+            }
+            assertNotificationCapabilityField(path, field, nested[key]);
+        }
+    }
+    assert(providerAvailabilitySet.has(actual.availability), 'notification availability must be a known readiness state');
+    assert(notificationOpenPaths.includes(actual.open), `notification open must be one of ${notificationOpenPaths.join(', ')}`);
+    const block = actual;
+    assertEqual(block.remote.supported, block.remote.addressing !== 'none', "notification remote.addressing must be 'none' exactly when remote.supported is false");
+    assertEqual(normalizedNotifications(block), normalizedNotifications(expected), 'notification capabilities must match the expected provider state');
+    assertEqual(snapshot.providerAvailability?.pushNotifications, block.availability, 'providerAvailability.pushNotifications must equal the notification capabilities availability');
+}
+function assertNotificationCapabilityField(path, field, value) {
+    switch (field.kind) {
+        case 'boolean':
+            assertEqual(typeof value, 'boolean', `notification capability ${path} must be a boolean`);
+            return;
+        case 'enum':
+            assert(field.values.includes(value), `notification capability ${path} must be one of ${field.values.join(', ')}`);
+            return;
+        case 'count':
+            assert(Number.isInteger(value) && value >= 1 && value <= 0xffff_ffff, `notification capability ${path} must be a positive integer`);
+            return;
+        case 'purposes':
+            assert(isDenseNotificationPurposeList(value), `notification capability ${path} must list only ${notificationPurposes.join(', ')}`);
+            return;
+    }
+}
+function isDenseNotificationPurposeList(value) {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index) || !notificationPurposes.includes(value[index])) {
+            return false;
+        }
+    }
+    return true;
+}
+function normalizedNotifications(value) {
+    if (value === undefined) {
+        return 'undefined';
+    }
+    return JSON.stringify([
+        ['availability', value.availability],
+        ['permission', sortedEntries(value.permission)],
+        ['remote', sortedEntries({ ...value.remote, purposes: [...value.remote.purposes].sort() })],
+        ['local', sortedEntries(value.local)],
+        ['open', value.open],
+    ]);
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertCommerceCapabilityBlock(snapshot, expected) {
+    const actual = snapshot.commerce;
+    assert(actual !== undefined, 'commerce capabilities are required: a gateway without a commerce provider reports createUnsupportedCommerceCapabilities()');
     assert(typeof actual === 'object' && actual !== null && !Array.isArray(actual), 'commerce capabilities must be a non-array record');
     const block = actual;
     const blockKeys = Object.keys(block).sort();
@@ -162,9 +270,6 @@ function assertCommerceCapabilityBlock(snapshot, expected) {
     }
     assert(providerAvailabilitySet.has(block.availability), 'commerce availability must be a known readiness state');
     assertEqual(normalizedCommerce(block), normalizedCommerce(expected), 'commerce capabilities must match the expected provider state');
-    const legacy = deriveLegacyCommerceCapabilities(block);
-    assertEqual(snapshot.nativeIap, legacy.nativeIap, 'nativeIap must equal the value derived from the commerce capabilities');
-    assertEqual(snapshot.subscriptionIap ?? false, legacy.subscriptionIap, 'subscriptionIap must equal the value derived from the commerce capabilities');
 }
 function normalizedCommerce(value) {
     if (value === undefined) {
@@ -191,41 +296,37 @@ function assertProviderAvailabilityShape(value) {
             && providerAvailabilitySet.has(state), 'provider availability must contain only known features and readiness states');
     }
 }
+// A deep copy of the plain records and lists, whatever their shape: the
+// oracle stays independent of the provider even when a fixture expects a
+// malformed block to be reported as is.
 function cloneExpectedCapabilities(value) {
-    return {
-        ...value,
-        ...(value.providerAvailability === undefined
-            ? {}
-            : { providerAvailability: { ...value.providerAvailability } }),
-        ...(value.commerce === undefined
-            ? {}
-            : {
-                commerce: {
-                    purchase: { ...value.commerce.purchase },
-                    catalog: { ...value.commerce.catalog },
-                    lifecycle: { ...value.commerce.lifecycle },
-                    authority: { ...value.commerce.authority },
-                    availability: value.commerce.availability,
-                },
-            }),
-    };
+    return clonePlainData(value);
+}
+function clonePlainData(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => clonePlainData(entry));
+    }
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, clonePlainData(entry)]));
+    }
+    return value;
 }
 function normalizedAvailability(value) {
     return JSON.stringify(Object.entries(value ?? {}).sort(([a], [b]) => a.localeCompare(b)));
 }
 function tryMutateSnapshot(snapshot) {
     try {
-        Reflect.set(snapshot, 'nativeIap', !snapshot.nativeIap);
+        Reflect.set(snapshot, 'nativeAds', !snapshot.nativeAds);
     }
     catch {
         // Frozen snapshots already satisfy the isolation requirement.
     }
     if (snapshot.providerAvailability !== undefined) {
         try {
-            const next = snapshot.providerAvailability.nativeIap === 'available'
+            const next = snapshot.providerAvailability.rewardedAds === 'available'
                 ? 'unsupported'
                 : 'available';
-            Reflect.set(snapshot.providerAvailability, 'nativeIap', next);
+            Reflect.set(snapshot.providerAvailability, 'rewardedAds', next);
         }
         catch {
             // A frozen nested readiness record already satisfies isolation.
@@ -234,6 +335,39 @@ function tryMutateSnapshot(snapshot) {
     if (snapshot.commerce !== undefined) {
         tryMutateCommerceSnapshot(snapshot.commerce);
     }
+    if (snapshot.notifications !== undefined) {
+        tryMutateNotificationSnapshot(snapshot.notifications);
+    }
+}
+// Every nested record and the purposes list are probed, as for commerce.
+function tryMutateNotificationSnapshot(notifications) {
+    const { purposes } = notifications.remote;
+    const probes = [
+        [notifications.permission, 'readable', !notifications.permission.readable],
+        [
+            notifications.remote,
+            'content',
+            notifications.remote.content === 'free-form' ? 'host-template' : 'free-form',
+        ],
+        // A reused list shows on the next read: emptied when it lists purposes,
+        // or holding one when it was empty.
+        purposes.length === 0 ? [purposes, '0', 'service'] : [purposes, 'length', 0],
+        [notifications.local, 'supported', !notifications.local.supported],
+        [
+            notifications,
+            'availability',
+            notifications.availability === 'available' ? 'unsupported' : 'available',
+        ],
+        [notifications, 'open', notifications.open === 'none' ? 'payload' : 'none'],
+    ];
+    for (const [target, key, next] of probes) {
+        try {
+            Reflect.set(target, key, next);
+        }
+        catch {
+            // Frozen values still need distinct references, checked across snapshots.
+        }
+    }
 }
 // Every nested block is probed: a gateway may rebuild the outer object while
 // reusing one mutable nested record across reads.
@@ -263,7 +397,9 @@ function hasCapabilityDifference(first, second) {
         .some((key) => (first[key] ?? false) !== (second[key] ?? false))
         || normalizedAvailability(first.providerAvailability)
             !== normalizedAvailability(second.providerAvailability)
-        || normalizedCommerce(first.commerce) !== normalizedCommerce(second.commerce);
+        || normalizedCommerce(first.commerce) !== normalizedCommerce(second.commerce)
+        || normalizedNotifications(first.notifications)
+            !== normalizedNotifications(second.notifications);
 }
 function assert(condition, message) {
     if (!condition) {

package/dist/commerce-capabilities.d.ts

@@ -1,9 +1,3 @@
 import type { CommerceCapabilities } from './index.js';
-export interface LegacyCommerceCapabilities {
-  readonly nativeIap: boolean;
-  readonly subscriptionIap: boolean;
-}
-/** Transition rule for the boolean `PlatformCapabilities` flags. */
-export declare function deriveLegacyCommerceCapabilities(capabilities: CommerceCapabilities): LegacyCommerceCapabilities;
 /** A fresh all-false snapshot; callers must not share or mutate a returned object. */
 export declare function createUnsupportedCommerceCapabilities(): CommerceCapabilities;

package/dist/commerce-capabilities.js

@@ -1,11 +1,5 @@
-/** Transition rule for the boolean `PlatformCapabilities` flags. */
-export function deriveLegacyCommerceCapabilities(capabilities) {
-    return {
-        nativeIap: capabilities.availability === 'available'
-            && (capabilities.purchase.consumable || capabilities.purchase.durable),
-        subscriptionIap: capabilities.purchase.subscription,
-    };
-}
+// Pure capability helpers shared by `./commerce` and `./capability-conformance`.
+// This file imports no validator so the conformance runner stays free of typia.
 /** A fresh all-false snapshot; callers must not share or mutate a returned object. */
 export function createUnsupportedCommerceCapabilities() {
     return {

package/dist/commerce-conformance.d.ts

@@ -355,6 +355,14 @@ export interface CommerceConformanceContext extends CommerceConformanceFixtureCo
 export interface CommerceConformanceRunOptions {
   /** Supplies a provider over the caller's fake SDK; defaults to the fake store or the reference wallet. */
   readonly createProvider?: (context: CommerceConformanceContext) => CommerceConformanceHarness | Promise<CommerceConformanceHarness>;
+  /**
+  * Supplies the runtime under test over the harness provider, backend, and
+  * journal; defaults to the reference reconciler
+  * (`createCommerceConformanceRuntime`). The reference run an adaptive
+  * vector is derived from always uses the reference reconciler, so the
+  * derived expectations stay the RFC's regardless of the runtime under test.
+  */
+  readonly createRuntime?: (input: CreateCommerceConformanceRuntimeInput, context: CommerceConformanceContext) => CommerceConformanceRuntime | Promise<CommerceConformanceRuntime>;
   readonly playerId?: string;
   readonly titleId?: string;
 }

package/dist/commerce-conformance.js

@@ -1107,7 +1107,7 @@ async function runVectorIn(vector, options, family) {
     // A harness that cannot be built is a failed run, never a rejected promise.
     let execution;
     try {
-        execution = await prepareExecution(vector, options.createProvider ?? createCommerceConformanceHarness, ids);
+        execution = await prepareExecution(vector, options.createProvider ?? createCommerceConformanceHarness, ids, options.createRuntime);
     }
     catch (error) {
         return failed([
@@ -1200,7 +1200,7 @@ async function runVectorIn(vector, options, family) {
         ...(adaptive === undefined ? {} : { adaptive }),
     };
 }
-async function prepareExecution(vector, createHarness, ids) {
+async function prepareExecution(vector, createHarness, ids, createRuntime) {
     const clock = createCommerceConformanceClock();
     const journal = createCommerceConformanceJournal();
     const harnessRef = {};
@@ -1224,14 +1224,17 @@ async function prepareExecution(vector, createHarness, ids) {
     };
     const harness = await createHarness(context);
     harnessRef.current = harness;
-    const runtime = createCommerceConformanceRuntime({
+    const runtimeInput = {
         provider: harness.provider,
         backend,
         journal,
         clock,
         catalog: context.catalog,
         playerId: ids.playerId,
-    });
+    };
+    const runtime = createRuntime === undefined
+        ? createCommerceConformanceRuntime(runtimeInput)
+        : await createRuntime(runtimeInput, context);
     return { vector, harness, runtime, backend, journal, clock, adaptation };
 }
 /** Runs every step; a thrown step ends the run with a failure at that step. */

package/dist/commerce-contract.d.ts

@@ -1,8 +1,8 @@
-import type { CommerceCapabilities, LogicalProductId, PlatformEvidenceEnvelope, StarterLogicalProductId } from './index.js';
+import type { CommerceCapabilities, CommerceFinishOwner, LogicalProductId, PlatformEvidenceEnvelope, PlatformPurchasePresentationEvent, StarterLogicalProductId } from './index.js';
 /**
 * Commerce v2 client contract types (RFC "Client contract"). This module is
 * typia-free on purpose: `./index` references `CommerceProvider` for
-* `PlatformGateway.commerceV2`, and headless consumers type-check
+* `PlatformGateway.commerce`, and headless consumers type-check
 * `@mpgd/platform` with `skipLibCheck: false` and no DOM lib, where typia's
 * root declarations do not compile. `./commerce` re-exports everything here
 * and builds the validators and JSON Schemas from these same types.
@@ -193,13 +193,29 @@ export interface FinishTransactionResult {
 }
 export interface CommerceProvider {
   readonly store: StoreId;
+  /**
+  * Trusted native presentation facts for the purchase UI (opened, closed,
+  * never started), independent of the purchase result. A provider whose host
+  * can prove when its payment surface closes (ONE play) offers it; the game
+  * runtime's presentation gate subscribes when present and treats a result
+  * alone as unknown.
+  */
+  readonly presentation?: {
+    subscribe(listener: (event: PlatformPurchasePresentationEvent) => void): () => void;
+  };
   getCapabilities(): Promise<CommerceCapabilities>;
   fetchProducts(input: FetchProductsInput): Promise<readonly StoreProduct[]>;
   /** Returns `launched` when the result arrives later as a `purchaseUpdated` event. */
   requestPurchase(input: RequestPurchaseInput): Promise<RequestPurchaseResult>;
   /** Purchases the store still reports as unfinished. */
   getAvailablePurchases(input?: GetAvailablePurchasesInput): Promise<readonly StorePurchase[]>;
-  /** Required when `lifecycle.finish` is 'client' or 'host'. */
+  /**
+  * Required when `lifecycle.finish` is 'client' or 'host'. Idempotent per
+  * transaction: the reconciler calls it again after a crash between a
+  * successful finish and its journal write, and on every pass while a
+  * finish keeps failing, so finishing an already finished transaction
+  * answers `{ finished: true }` rather than failing.
+  */
   finishTransaction?(input: FinishTransactionInput): Promise<FinishTransactionResult>;
   /** Asks the store to resynchronize, for example `AppStore.sync`. */
   restorePurchases?(): Promise<void>;
@@ -219,4 +235,27 @@ export interface ActiveSubscription {
   readonly expiresAt: IsoTimestamp;
   readonly autoRenew: boolean;
 }
+/** What the backend accepts for one store (RFC "Provider capabilities endpoint"). */
+export interface CommerceServiceStoreCapabilities {
+  readonly store: StoreId;
+  /** Evidence schemas the backend routes for this store. */
+  readonly schemas: readonly NonEmptyString[];
+  /** Who finishes a granted purchase of this store, as the backend expects it. */
+  readonly finish: CommerceFinishOwner;
+  readonly purchase: {
+    readonly consumable: boolean;
+    readonly durable: boolean;
+    readonly subscription: boolean;
+  };
+}
+/**
+* The backend's published commerce capabilities (RFC "Provider capabilities
+* endpoint"): the protocol version it speaks and one row per store its
+* evidence registry accepts. The client runtime compares it with its
+* provider's capability block at start.
+*/
+export interface CommerceServiceCapabilities {
+  readonly commerceProtocolVersion: NonEmptyString;
+  readonly stores: readonly CommerceServiceStoreCapabilities[];
+}
 export {};

package/dist/commerce.d.ts

@@ -1,7 +1,7 @@
 import { type tags } from 'typia';
-import { PlatformOperationError, type CommerceAdapter, type CommerceCapabilities } from './index.js';
-import type { ActiveSubscription, CommerceErrorCode, CommerceErrorInfo, CommerceEvent, CommerceLogicalProductId, CommerceProvider, FetchProductsInput, FinishTransactionInput, FinishTransactionResult, GetAvailablePurchasesInput, IsoTimestamp, NonEmptyString, NonNegativeInteger, PositiveQuantity, PurchaseKind, RequestPurchaseInput, RequestPurchaseResult, StoreId, StoreProduct, StorePurchase } from './commerce-contract.js';
-export { createUnsupportedCommerceCapabilities, deriveLegacyCommerceCapabilities, type LegacyCommerceCapabilities, } from './commerce-capabilities.js';
+import { PlatformOperationError, type CommerceCapabilities } from './index.js';
+import type { ActiveSubscription, CommerceErrorCode, CommerceErrorInfo, CommerceEvent, CommerceLogicalProductId, CommerceServiceCapabilities, FetchProductsInput, FinishTransactionInput, FinishTransactionResult, GetAvailablePurchasesInput, IsoTimestamp, NonEmptyString, NonNegativeInteger, PositiveQuantity, PurchaseKind, RequestPurchaseInput, RequestPurchaseResult, StoreId, StoreProduct, StorePurchase } from './commerce-contract.js';
+export { createUnsupportedCommerceCapabilities } from './commerce-capabilities.js';
 export type { CommerceAccountBindingPolicy, CommerceAuthorityCapabilities, CommerceCapabilities, CommerceCatalogCapabilities, CommerceEvidenceAuthority, CommerceFinishOwner, CommerceLifecycleCapabilities, CommercePurchaseCapabilities, } from './index.js';
 /**
 * Commerce v2 client contract. Pure types, validators, and helpers only: no
@@ -11,7 +11,7 @@ export type { CommerceAccountBindingPolicy, CommerceAuthorityCapabilities, Comme
 */
 export declare const commerceProtocolVersion: '2.0.0-draft.1';
 export declare const commerceProtocol: 'mpgd.commerce.v2';
-export type { ActiveSubscription, ActiveSubscriptionState, CommerceErrorCode, CommerceErrorInfo, CommerceEvent, CommerceLogicalProductId, CommerceProvider, FetchProductsInput, FetchProductsType, FinishTransactionInput, FinishTransactionResult, GetAvailablePurchasesInput, PurchaseKind, PurchaseSource, RequestPurchaseInput, RequestPurchaseResult, StoreId, StoreOffer, StorePrice, StoreProduct, StorePurchase, StorePurchaseAccountBinding, StorePurchaseState, } from './commerce-contract.js';
+export type { ActiveSubscription, ActiveSubscriptionState, CommerceErrorCode, CommerceErrorInfo, CommerceEvent, CommerceLogicalProductId, CommerceProvider, CommerceServiceCapabilities, CommerceServiceStoreCapabilities, FetchProductsInput, FetchProductsType, FinishTransactionInput, FinishTransactionResult, GetAvailablePurchasesInput, PurchaseKind, PurchaseSource, RequestPurchaseInput, RequestPurchaseResult, StoreId, StoreOffer, StorePrice, StoreProduct, StorePurchase, StorePurchaseAccountBinding, StorePurchaseState, } from './commerce-contract.js';
 export declare const commerceErrorCodes: readonly ["USER_CANCELLED", "OUTCOME_UNKNOWN", "ALREADY_OWNED", "IN_PROGRESS", "ITEM_UNAVAILABLE", "NOT_PREPARED", "NETWORK", "STORE_UNAVAILABLE", "CONFIGURATION_REQUIRED", "ACTION_REQUIRED", "ACCOUNT_BINDING_REQUIRED", "INSUFFICIENT_BALANCE", "INVALID_RESPONSE", "UNKNOWN"];
 /** Bridge event envelope; `sequence` is per session and starts at 0. */
 export interface CommerceEventEnvelope {
@@ -250,11 +250,16 @@ export interface DerivedPurchaseIdempotencyKeyInput {
 * the same key: `store:<storeId>:<transactionId>` by default, with each
 * component percent-encoded (`encodeURIComponent`) so ids containing `:`
 * cannot collide, and the forms v1 ledgers already use for Google Play
-* (`play-token-sha256:<hex>`) and Apps in Toss (`apps-in-toss:purchase:<orderId>`),
-* which stay byte-identical.
+* (`play-token-sha256:<hex>`) and Apps in Toss
+* (`apps-in-toss:purchase:<encodeURIComponent(orderId)>`), which stay
+* byte-identical.
 */
 export declare function createDerivedPurchaseIdempotencyKey(input: DerivedPurchaseIdempotencyKeyInput): Promise<string>;
-/** Byte-for-byte the v1 `createGooglePlayTokenTransactionId` form; A4 replaces the two copies with this helper. */
+/**
+* The `play-token-sha256:<hex>` idempotency key of a Google Play purchase
+* token. The one shared helper: the plugin and `@mpgd/game-services` use it,
+* and ledgers written by v1 releases keep deduplicating against it.
+*/
 export declare function createGooglePlayTokenPurchaseKey(purchaseToken: string): Promise<string>;
 export declare const commerceEventBufferLimit = 64;
 export interface CommerceEventBuffer {
@@ -292,6 +297,8 @@ export declare const isActiveSubscription: (input: unknown) => input is ActiveSu
 export declare const assertFetchProductsInput: (input: unknown) => FetchProductsInput;
 export declare const assertCommerceCapabilities: (input: unknown) => CommerceCapabilities;
 export declare const isCommerceCapabilities: (input: unknown) => input is CommerceCapabilities;
+export declare const assertCommerceServiceCapabilities: (input: unknown) => CommerceServiceCapabilities;
+export declare const isCommerceServiceCapabilities: (input: unknown) => input is CommerceServiceCapabilities;
 export declare const assertCommerceErrorInfo: (input: unknown) => CommerceErrorInfo;
 export declare const assertCreditOffer: (input: unknown) => CreditOffer;
 export declare const assertCreditSpendInput: (input: unknown) => CreditSpendInput;
@@ -314,16 +321,3 @@ export declare const assertCommerceBridgeFinishTransactionPayload: (input: unkno
 export declare const assertCommerceBridgeFinishTransactionResult: (input: unknown) => FinishTransactionResult;
 export declare const assertCommerceBridgeRestorePurchasesPayload: (input: unknown) => CommerceBridgeRestorePurchasesPayload;
 export declare const assertCommerceBridgeRestorePurchasesResult: (input: unknown) => CommerceBridgeRestorePurchasesResult;
-export interface ToCommerceAdapterOptions {
-  /** Forwarded to `getAvailablePurchases` during `restore`. Defaults to false. */
-  readonly includePending?: boolean;
-}
-/**
-* Serves v1 `CommerceAdapter` callers from a v2 provider. The wrapper never
-* grants: a `purchased` outcome becomes a `completed` result with no
-* entitlements, and `authoritativeGrant` appears only when the provider reports
-* an adapter settlement that already points at a ledger entry. `restore`
-* returns settled purchases from `getAvailablePurchases` and no entitlements;
-* entitlements come from the ledger, not from the provider.
-*/
-export declare function toCommerceAdapter(provider: CommerceProvider, options?: ToCommerceAdapterOptions): CommerceAdapter;