@mpgd/platform 0.17.0 → 0.19.0

package/dist/capability-conformance.js

@@ -1,3 +1,4 @@
+import { deriveLegacyCommerceCapabilities } from './commerce-capabilities.js';
 export const platformCapabilityKeys = Object.freeze([
     'nativeIap',
     'nativeAds',
@@ -22,6 +23,7 @@ const allowedPlatformCapabilityKeys = Object.freeze([
 const allowedPlatformCapabilityKeySet = new Set([
     ...allowedPlatformCapabilityKeys,
     'providerAvailability',
+    'commerce',
 ]);
 const optionalPlatformCapabilityKeySet = new Set(optionalPlatformCapabilityKeys);
 const providerFeatureSet = new Set([
@@ -41,6 +43,19 @@ 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.
+const commerceCapabilityBlockKeys = Object.freeze({
+    purchase: ['consumable', 'durable', 'subscription', 'quantity'],
+    catalog: ['products', 'offers', 'localizedPrice'],
+    lifecycle: ['availablePurchases', 'pending', 'restore', 'events', 'finish'],
+    authority: ['evidence', 'accountBinding'],
+});
+const commerceCapabilityEnums = Object.freeze({
+    'lifecycle.finish': ['client', 'server', 'host', 'none'],
+    'authority.evidence': ['client-token', 'host-callback', 'adapter-settled', 'server-push'],
+    'authority.accountBinding': ['required', 'optional', 'host'],
+});
 /**
  * Runs provider-neutral capability checks against real adapter gateways or
  * target-configured wrappers. Every read must return a complete boolean
@@ -116,6 +131,55 @@ 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);
+}
+function assertCommerceCapabilityBlock(snapshot, expected) {
+    const actual = snapshot.commerce;
+    if (actual === undefined) {
+        assert(expected === undefined, 'commerce capabilities must be present when the fixture expects them');
+        return;
+    }
+    assert(expected !== undefined, 'commerce capabilities must be absent when the fixture omits them');
+    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();
+    assertEqual(JSON.stringify(blockKeys), JSON.stringify([...Object.keys(commerceCapabilityBlockKeys), 'availability'].sort()), 'commerce capabilities must contain exactly purchase, catalog, lifecycle, authority, and availability');
+    for (const [group, keys] of Object.entries(commerceCapabilityBlockKeys)) {
+        const nested = block[group];
+        assert(typeof nested === 'object' && nested !== null && !Array.isArray(nested), `commerce ${group} capabilities must be a non-array record`);
+        const record = nested;
+        assertEqual(JSON.stringify(Object.keys(record).sort()), JSON.stringify([...keys].sort()), `commerce ${group} capabilities must contain exactly ${keys.join(', ')}`);
+        for (const key of keys) {
+            const path = `${group}.${key}`;
+            const allowed = commerceCapabilityEnums[path];
+            if (allowed === undefined) {
+                assertEqual(typeof record[key], 'boolean', `commerce capability ${path} must be a boolean`);
+            }
+            else {
+                assert(allowed.includes(record[key]), `commerce capability ${path} must be one of ${allowed.join(', ')}`);
+            }
+        }
+    }
+    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) {
+        return 'undefined';
+    }
+    return JSON.stringify([
+        ['purchase', sortedEntries(value.purchase)],
+        ['catalog', sortedEntries(value.catalog)],
+        ['lifecycle', sortedEntries(value.lifecycle)],
+        ['authority', sortedEntries(value.authority)],
+        ['availability', value.availability],
+    ]);
+}
+function sortedEntries(value) {
+    return Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
 }
 function assertProviderAvailabilityShape(value) {
     if (value === undefined) {
@@ -133,6 +197,17 @@ function cloneExpectedCapabilities(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,
+                },
+            }),
     };
 }
 function normalizedAvailability(value) {
@@ -156,12 +231,39 @@ function tryMutateSnapshot(snapshot) {
             // A frozen nested readiness record already satisfies isolation.
         }
     }
+    if (snapshot.commerce !== undefined) {
+        tryMutateCommerceSnapshot(snapshot.commerce);
+    }
+}
+// Every nested block is probed: a gateway may rebuild the outer object while
+// reusing one mutable nested record across reads.
+function tryMutateCommerceSnapshot(commerce) {
+    const probes = [
+        [commerce.purchase, 'consumable', !commerce.purchase.consumable],
+        [commerce.catalog, 'products', !commerce.catalog.products],
+        [commerce.lifecycle, 'events', !commerce.lifecycle.events],
+        [
+            commerce.authority,
+            'accountBinding',
+            commerce.authority.accountBinding === 'host' ? 'optional' : 'host',
+        ],
+        [commerce, 'availability', commerce.availability === 'available' ? 'unsupported' : 'available'],
+    ];
+    for (const [target, key, next] of probes) {
+        try {
+            Reflect.set(target, key, next);
+        }
+        catch {
+            // A frozen nested commerce block already satisfies isolation.
+        }
+    }
 }
 function hasCapabilityDifference(first, second) {
     return allowedPlatformCapabilityKeys
         .some((key) => (first[key] ?? false) !== (second[key] ?? false))
         || normalizedAvailability(first.providerAvailability)
-            !== normalizedAvailability(second.providerAvailability);
+            !== normalizedAvailability(second.providerAvailability)
+        || normalizedCommerce(first.commerce) !== normalizedCommerce(second.commerce);
 }
 function assert(condition, message) {
     if (!condition) {

package/dist/commerce-capabilities.d.ts

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,24 @@
+/** 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,
+    };
+}
+/** A fresh all-false snapshot; callers must not share or mutate a returned object. */
+export function createUnsupportedCommerceCapabilities() {
+    return {
+        purchase: { consumable: false, durable: false, subscription: false, quantity: false },
+        catalog: { products: false, offers: false, localizedPrice: false },
+        lifecycle: {
+            availablePurchases: false,
+            pending: false,
+            restore: false,
+            events: false,
+            finish: 'none',
+        },
+        authority: { evidence: 'client-token', accountBinding: 'optional' },
+        availability: 'unsupported',
+    };
+}

package/dist/commerce-conformance.d.ts

@@ -0,0 +1,386 @@
+import { type ActiveSubscription, type CommerceBillingAuthority, type CommerceCapabilities, type CommerceErrorCode, type CommerceErrorInfo, type CommerceEvent, type CommerceLogicalProductId, type CommerceProvider, type CommercePurchaseState, type CreditBalance, type CreditDebit, type CreditEntitlement, type CreditLot, type CreditLotSpendScope, type CreditMembershipTerms, type CreditOffer, type CreditSpendInput, type CreditSpendResult, type CreditWalletClient, type FetchProductsInput, type PurchaseKind, type RequestPurchaseInput, type RequestPurchaseResult, type StoreId, type StoreProduct, type StorePurchase } from './commerce.js';
+import type { CommerceConformanceCatalogEntry, CommerceConformanceErrorFixture, CommerceConformanceFinishResultFixture, CommerceConformanceLotFixture, CommerceConformanceProfile, CommerceConformancePurchaseFixture, CommerceConformanceRequestResultFixture, CommerceConformanceSubscriptionEventType, CommerceConformanceVector, CommerceConformanceVerifyDecision } from './commerce-vectors.js';
+import type { PlatformEvidenceEnvelope } from './index.js';
+/**
+* Commerce v2 conformance runner (RFC "Conformance vectors") with the in-memory
+* reference pieces every vector needs: a fake clock, a fake store with its
+* provider, a fake backend and ledger, an in-memory journal, the reference
+* reconciler runtime, and a reference credit wallet with its provider. Pure
+* in-process code: no Phaser, DOM, network, or SDK imports. Nothing here
+* grants outside the fake ledger, and the fake ledger only writes what a
+* vector scripts through `queueVerify`, `push`, or `revoke`.
+*
+* Store (B-phase) providers run the same vectors by supplying
+* `createProvider` and translating the store actor steps into their own fake
+* SDK; the reconciler, journal, backend, and matcher stay shared.
+*/
+export declare const commerceConformanceDefaultPlayerId = "player-1";
+export declare const commerceConformanceDefaultTitleId = "title-a";
+export declare const commerceConformanceDefaultClockStart = "2026-10-01T00:00:00Z";
+/** An operation the vector did not script; it fails the vector with its message. */
+export declare class CommerceConformanceScriptError extends Error {
+  readonly name = "CommerceConformanceScriptError";
+}
+export interface CommerceConformanceClock {
+  /** ISO-8601 timestamp of the fake "now". */
+  now(): string;
+  set(at: string): void;
+}
+export declare function createCommerceConformanceClock(initial?: string): CommerceConformanceClock;
+/** Canonical `YYYY-MM-DDTHH:mm:ssZ`; milliseconds are kept only when non-zero. */
+export declare function normalizeIsoTimestamp(input: string): string;
+/** Adds an ISO-8601 duration (`P30D`, `P1M`, `PT12H`, ...) to a timestamp, in UTC calendar units. */
+export declare function addIsoDuration(at: string, duration: string): string;
+/** Capabilities of a vector profile: omitted blocks default to all supported and `available`. */
+export declare function createCommerceConformanceCapabilities(profile: CommerceConformanceProfile): CommerceCapabilities;
+export interface CommerceConformanceFixtureContext {
+  readonly profile: CommerceConformanceProfile;
+  readonly catalog: readonly CommerceConformanceCatalogEntry[];
+  readonly playerId: string;
+}
+/** Fake evidence for a fixture purchase: `fixture.<store>.v1` carrying the token. */
+export declare function createCommerceConformanceEvidence(store: StoreId, token: string): PlatformEvidenceEnvelope;
+/**
+* Fills vector purchase shorthand into a typed `StorePurchase`: the profile's
+* store, quantity 1, the catalog logical id of the SKU, fake evidence, and the
+* account binding the profile's authority block implies.
+*/
+export declare function fillCommerceConformancePurchase(fixture: CommerceConformancePurchaseFixture, context: CommerceConformanceFixtureContext): StorePurchase;
+export declare function commerceErrorInfoOfFixture(fixture: CommerceConformanceErrorFixture): CommerceErrorInfo;
+export interface CommerceConformanceFinishCall {
+  readonly by: 'client' | 'host';
+  readonly transactionId: string;
+  readonly ledgerEntryId: string;
+  readonly isConsumable: boolean;
+  readonly result: 'finished' | 'unfinished' | CommerceErrorCode;
+}
+/** The store actor of a vector: scripted answers, store-side events, and store observations. */
+export interface CommerceConformanceStoreActor {
+  /** Calls that reached the store's purchase UI. */
+  readonly purchaseUiOpened: number;
+  readonly finishCalls: readonly CommerceConformanceFinishCall[];
+  complete(purchase: CommerceConformancePurchaseFixture): void;
+  update(purchase: CommerceConformancePurchaseFixture): void;
+  error(input: {
+    readonly logicalId?: CommerceLogicalProductId;
+    readonly error: CommerceConformanceErrorFixture;
+  }): void;
+  queueRequest(result: CommerceConformanceRequestResultFixture): void;
+  queueFinish(result: CommerceConformanceFinishResultFixture): void;
+  /** The backend's finalizer consumed the purchase (`lifecycle.finish: 'server'`). */
+  finalize?(input: {
+    readonly transactionId: string;
+    readonly ledgerEntryId: string;
+  }): void | Promise<void>;
+}
+export interface CommerceConformanceStore extends CommerceConformanceStoreActor {
+  /** The `CommerceProvider` over this fake store. */
+  readonly provider: CommerceProvider;
+  /** Purchases the store still reports as unfinished. */
+  readonly purchases: readonly StorePurchase[];
+  readonly restoreCalls: number;
+  /** Removes a purchase from the unfinished list. */
+  markFinished(transactionId: string): void;
+}
+export type CreateCommerceConformanceStoreInput = CommerceConformanceFixtureContext;
+/**
+* Fake store: answers `launched` unless a `queueRequest` entry is queued,
+* `{ finished: true }` unless a `queueFinish` entry is queued, lists reported
+* purchases until they are finished, and buffers events emitted before the
+* first listener with `createCommerceEventBuffer`.
+*/
+export declare function createCommerceConformanceStore(input: CreateCommerceConformanceStoreInput): CommerceConformanceStore;
+export interface CommerceVerifyRequest {
+  readonly idempotencyKey: string;
+  readonly playerId: string;
+  readonly store: StoreId;
+  readonly transactionId: string;
+  readonly token: string;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly quantity: number;
+  readonly evidence: PlatformEvidenceEnvelope;
+}
+export interface CommerceVerifyResponse {
+  readonly status: 'granted' | 'pending' | 'rejected';
+  readonly ledgerEntryId?: string;
+  /** Reported for `lifecycle.finish: 'server'` stores. */
+  readonly finalization?: 'pending' | 'completed';
+  readonly alreadyProcessed?: boolean;
+}
+export type CommerceLedgerEntry = {
+  readonly entryId: string;
+  readonly type: 'grant';
+  readonly logicalId: CommerceLogicalProductId;
+  readonly store: StoreId;
+  readonly transactionId: string;
+  readonly idempotencyKey?: string;
+  /** Written by the host's fulfillment path rather than a verify call. */
+  readonly pushed?: boolean;
+} | {
+  readonly entryId: string;
+  readonly type: 'revoke';
+  readonly logicalId: CommerceLogicalProductId;
+  readonly reverses: string;
+  readonly reason: string;
+};
+export interface CommerceLedgerStatus {
+  readonly ledgerEntryId: string;
+  readonly status: 'active' | 'reversed' | 'unknown';
+  readonly reversedBy?: string;
+}
+/** What the reference runtime needs from a backend. */
+export interface CommerceConformanceBackendClient {
+  verifyPurchase(request: CommerceVerifyRequest): Promise<CommerceVerifyResponse>;
+  getLedgerStatus(ledgerEntryIds: readonly string[]): Promise<readonly CommerceLedgerStatus[]>;
+}
+export interface CommerceConformanceBackend extends CommerceConformanceBackendClient {
+  readonly verifyRequests: readonly CommerceVerifyRequest[];
+  readonly ledger: readonly CommerceLedgerEntry[];
+  queueVerify(decision: CommerceConformanceVerifyDecision): void;
+  /** Writes a server-push grant keyed by transaction id; a retry for the same transaction replays the original entry. */
+  push(input: {
+    readonly transactionId: string;
+    readonly entryId: string;
+    readonly logicalId: CommerceLogicalProductId;
+    readonly store?: StoreId;
+  }): void;
+  revoke(input: {
+    readonly ledgerEntryId: string;
+    readonly entryId: string;
+    readonly reason: string;
+  }): void;
+  /** Grants the ledger still holds active. */
+  entitlements(): readonly {
+    readonly id: string;
+    readonly logicalId: CommerceLogicalProductId;
+  }[];
+}
+export interface CreateCommerceConformanceBackendInput {
+  /** The server-side finalizer, invoked when a decision reports `finalization: 'completed'`. */
+  readonly finalize?: (input: {
+    readonly store: StoreId;
+    readonly transactionId: string;
+    readonly ledgerEntryId: string;
+    readonly logicalId: CommerceLogicalProductId;
+  }) => void | Promise<void>;
+}
+/**
+* Fake backend: every verify call consumes the next `queueVerify` decision in
+* order and is logged; an unqueued verify is an unscripted operation. A
+* `granted` decision makes sure the ledger holds the entry, so a replayed
+* grant and a host-pushed grant never create a second entry.
+*/
+export declare function createCommerceConformanceBackend(input?: CreateCommerceConformanceBackendInput): CommerceConformanceBackend;
+export interface CommerceJournalRecord {
+  /** The purchase idempotency key: the game's key or a derived key. */
+  readonly key: string;
+  readonly revision: number;
+  readonly playerId: string;
+  readonly store: StoreId;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly kind: PurchaseKind;
+  readonly origin: 'game' | 'discovered';
+  readonly state: CommercePurchaseState;
+  readonly updatedAt: string;
+  readonly purchase?: StorePurchase;
+  /** Saved before the first send and resent unchanged on later passes. */
+  readonly request?: CommerceVerifyRequest;
+  readonly ledgerEntryId?: string;
+  readonly error?: CommerceErrorInfo;
+  readonly revokedBy?: string;
+}
+/**
+* Purchase journal with the compare-and-replace semantics of
+* `MonetizationOperationStore`. A game supplies a durable, atomic
+* implementation; the in-memory one below exists for conformance runs.
+*/
+export interface CommerceJournalStore {
+  /** Atomically insert or return the existing record for this key. */
+  reserve(record: CommerceJournalRecord): Promise<{
+    readonly created: boolean;
+    readonly record: CommerceJournalRecord;
+  }>;
+  read(key: string): Promise<CommerceJournalRecord | undefined>;
+  /** Compare-and-swap on `expectedRevision`; the stored record carries the next revision. */
+  replace(expectedRevision: number, record: CommerceJournalRecord): Promise<CommerceJournalRecord>;
+  /** Non-terminal records; terminal records stay addressable by `read`. */
+  listRecoverable(playerId: string): Promise<readonly CommerceJournalRecord[]>;
+  /** Records in `granted`, `finishing`, or `finished` kept for revocation reporting. */
+  listGranted(playerId: string): Promise<readonly CommerceJournalRecord[]>;
+}
+export interface CommerceConformanceJournal extends CommerceJournalStore {
+  readonly keys: readonly string[];
+  /** Every state revision of a key, in write order. */
+  history(key: string): readonly CommercePurchaseState[];
+  /** `history` for every key, in creation order. */
+  snapshot(): Readonly<Record<string, readonly CommercePurchaseState[]>>;
+}
+/** In-memory journal that keeps every revision so `expect.journal` can read the full sequence. */
+export declare function createCommerceConformanceJournal(): CommerceConformanceJournal;
+export interface CommerceConformanceRuntime {
+  readonly started: boolean;
+  /** Subscribe, read available purchases when declared, then reconcile until idle. */
+  start(): Promise<void>;
+  /** Drop in-memory state; the journal, store, ledger, and wallet are kept. */
+  stop(): Promise<void>;
+  /** One reconcile pass, then any passes that events arriving meanwhile trigger. */
+  reconcile(): Promise<void>;
+  /** Reconcile while a trigger is pending; a no-op when stopped. */
+  runUntilIdle(): Promise<void>;
+  requestPurchase(input: RequestPurchaseInput): Promise<RequestPurchaseResult>;
+  fetchProducts(input?: FetchProductsInput): Promise<readonly StoreProduct[]>;
+}
+export interface CreateCommerceConformanceRuntimeInput {
+  readonly provider: CommerceProvider;
+  readonly backend: CommerceConformanceBackendClient;
+  readonly journal: CommerceJournalStore;
+  readonly clock: CommerceConformanceClock;
+  readonly catalog: readonly CommerceConformanceCatalogEntry[];
+  readonly playerId: string;
+}
+/**
+* Reference reconciler. Every transition is its own journal revision written
+* through compare-and-replace; the backend is in-process, so there is no
+* transport, but a thrown finish or verify keeps the state for the next pass
+* as a transport failure would. Only a ledger entry moves a record to
+* `granted`, and only a ledger revocation moves it to `revoked`.
+*/
+export declare function createCommerceConformanceRuntime(input: CreateCommerceConformanceRuntimeInput): CommerceConformanceRuntime;
+export interface CommerceScheduledDebit extends CreditDebit {
+  readonly idempotencyKey: string;
+}
+export interface CommerceConformanceSubscriptionEvent {
+  /** Stable id `<subscriptionId>:<periodIndex>:<type>`, so redelivery is idempotent. */
+  readonly eventId: string;
+  readonly type: CommerceConformanceSubscriptionEventType;
+  readonly subscriptionId: string;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly periodIndex: number;
+  readonly expiresAt: string;
+  readonly reason?: CommerceErrorCode;
+}
+export interface CommerceConformanceMembershipStart {
+  readonly subscriptionId: string;
+  readonly titleId: string;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly terms: CreditMembershipTerms;
+}
+export type CommerceConformanceMembershipResult = {
+  readonly status: 'started';
+  readonly subscription: ActiveSubscription;
+  readonly entitlementId: string;
+} | {
+  readonly status: 'rejected';
+  readonly error: CommerceErrorInfo;
+};
+/** The wallet actor of a vector: wallet steps plus wallet observations. */
+export interface CommerceConformanceWalletActor {
+  readonly lots: readonly CreditLot[];
+  /** Every debit of every processed spend, in order; replays add nothing. */
+  readonly debits: readonly CommerceScheduledDebit[];
+  readonly subscriptionEvents: readonly CommerceConformanceSubscriptionEvent[];
+  creditFromGrant(lot: CommerceConformanceLotFixture, options?: {
+    readonly spendScope?: CreditLotSpendScope;
+  }): CreditLot;
+  spend(input: CreditSpendInput): Promise<CreditSpendResult>;
+  /** Runs the renewal scheduler for memberships whose paid period has ended. */
+  renewDue(): Promise<void>;
+  getBalance(input: {
+    readonly titleId: string;
+  }): Promise<CreditBalance>;
+  getActiveSubscriptions(): Promise<readonly ActiveSubscription[]>;
+  /** The backend's finalizer redeemed the entitlement (`lifecycle.finish: 'server'`). */
+  finalize?(input: {
+    readonly transactionId: string;
+    readonly ledgerEntryId: string;
+  }): void | Promise<void>;
+}
+export interface CommerceConformanceWallet extends CreditWalletClient, CommerceConformanceWalletActor {
+  readonly entitlements: readonly CreditEntitlement[];
+  startMembership(input: CommerceConformanceMembershipStart): Promise<CommerceConformanceMembershipResult>;
+  subscribe(listener: (event: CommerceEvent) => void): () => void;
+}
+export interface CreateCommerceConformanceWalletInput {
+  readonly store: StoreId;
+  readonly clock: CommerceConformanceClock;
+  readonly currencies: readonly string[];
+  /** Offers served by `listOffers`; defaults to none. */
+  readonly offers?: readonly CreditOffer[];
+}
+/**
+* Reference in-memory wallet implementing the RFC "Credit lots" and "Billing
+* authority and memberships" rules: lot ids equal ledger entry ids, spend
+* scope derives from the lot origin, spends consume eligible lots in the
+* fixed order, are idempotent by key, and debit nothing on
+* `INSUFFICIENT_BALANCE`; memberships debit `membership:<id>:<period>` per
+* paid period and lapse at period end when the eligible balance runs out.
+*/
+export declare function createCommerceConformanceWallet(input: CreateCommerceConformanceWalletInput): CommerceConformanceWallet;
+/** Store lots are title-scoped, off-store lots cross-title, promotion lots as issued (title by default). */
+export declare function deriveCreditLotSpendScope(origin: CreditLot['origin'], explicit?: CreditLotSpendScope): CreditLotSpendScope;
+/** RFC spend order: earliest `expiresAt` (none last), `title` before `cross-title`, oldest `createdAt`, then `lotId`. */
+export declare function compareCreditLotSpendOrder(left: CreditLot, right: CreditLot): number;
+export interface CreateCommerceConformanceWalletProviderInput {
+  readonly wallet: CommerceConformanceWallet;
+  readonly profile: CommerceConformanceProfile;
+  readonly catalog: readonly CommerceConformanceCatalogEntry[];
+  readonly currencies: readonly string[];
+  readonly billingAuthority: CommerceBillingAuthority;
+  readonly titleId: string;
+  readonly clock: CommerceConformanceClock;
+}
+/**
+* `CommerceProvider` over the reference wallet: `fetchProducts` lists the
+* wallet's offers (catalog-derived offers only when the wallet lists none),
+* `requestPurchase` spends the offer price times the requested quantity
+* (outcome `purchased`, `settlement` set, evidence adapter-settled),
+* `getAvailablePurchases` lists unredeemed entitlements, and finishing is the
+* backend's `redeem`. Memberships exist only where the billing authority is
+* `host`.
+*/
+export declare function createCommerceConformanceWalletProvider(input: CreateCommerceConformanceWalletProviderInput): CommerceProvider;
+export interface CommerceConformanceHarness {
+  readonly provider: CommerceProvider;
+  /** Handles `store` steps; required by store vectors. */
+  readonly store?: CommerceConformanceStoreActor;
+  /** Handles `wallet` steps; required by wallet vectors. */
+  readonly wallet?: CommerceConformanceWalletActor;
+}
+export interface CommerceConformanceContext extends CommerceConformanceFixtureContext {
+  readonly vector: CommerceConformanceVector;
+  readonly titleId: string;
+  readonly clock: CommerceConformanceClock;
+  readonly backend: CommerceConformanceBackend;
+  readonly journal: CommerceConformanceJournal;
+}
+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>;
+  readonly playerId?: string;
+  readonly titleId?: string;
+}
+export interface CommerceConformanceFailure {
+  readonly path: string;
+  readonly expected: unknown;
+  readonly actual: unknown;
+}
+export interface CommerceConformanceVectorResult {
+  readonly vector: string;
+  readonly passed: boolean;
+  readonly failures: readonly CommerceConformanceFailure[];
+}
+export declare function createCommerceConformanceHarness(context: CommerceConformanceContext): CommerceConformanceHarness;
+/**
+* Runs one vector: executes every step, lets the runtime run until idle after
+* each, then matches `expect`. Matching compares only the listed fields; arrays
+* compare in order and by length; a listed `journal` is the whole journal.
+* Any unscripted operation fails the vector at the step that needed it.
+*/
+export declare function runCommerceConformanceVector(vector: CommerceConformanceVector, options?: CommerceConformanceRunOptions): Promise<CommerceConformanceVectorResult>;
+export declare function runCommerceConformanceVectors(vectors: readonly CommerceConformanceVector[], options?: CommerceConformanceRunOptions): Promise<readonly CommerceConformanceVectorResult[]>;
+/**
+* Partial match: an expected object asserts only its listed keys, an expected
+* array asserts its length and each element in order, and primitives compare
+* strictly. Failures name the deepest differing path.
+*/
+export declare function matchPartial(expected: unknown, actual: unknown, path: string, failures: CommerceConformanceFailure[]): void;