@mpgd/platform 0.19.0 → 0.21.0

package/dist/commerce-conformance.js

@@ -1,4 +1,7 @@
 import { assertCommercePurchaseTransition, assertRequestPurchaseSupported, CommerceError, commerceErrorInfoOf, createCommerceEventBuffer, createDerivedPurchaseIdempotencyKey, isTerminalCommercePurchaseState, } from './commerce.js';
+import { createCreditCommerceProvider, createInMemoryCreditWallet, normalizeIsoTimestamp, } from './commerce-wallet.js';
+// The wallet rules moved to `./commerce-wallet` with B7; they stay importable here.
+export { addIsoDuration, compareCreditLotSpendOrder, deriveCreditLotSpendScope, normalizeIsoTimestamp, } from './commerce-wallet.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
@@ -10,7 +13,11 @@ import { assertCommercePurchaseTransition, assertRequestPurchaseSupported, Comme
  *
  * 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.
+ * SDK; the reconciler, journal, backend, and matcher stay shared. A vector
+ * flagged `profile.adaptive` then matches expectations derived from the
+ * provider's declared capabilities rather than its fixture profile; see
+ * `deriveAdaptiveCommerceConformanceExpectation` and
+ * `commerceConformanceAdaptiveSkipReason`.
  */
 export const commerceConformanceDefaultPlayerId = 'player-1';
 export const commerceConformanceDefaultTitleId = 'title-a';
@@ -28,31 +35,6 @@ export function createCommerceConformanceClock(initial = commerceConformanceDefa
         },
     };
 }
-/** Canonical `YYYY-MM-DDTHH:mm:ssZ`; milliseconds are kept only when non-zero. */
-export function normalizeIsoTimestamp(input) {
-    const millis = Date.parse(input);
-    if (Number.isNaN(millis)) {
-        throw new TypeError(`Invalid ISO-8601 timestamp: ${input}`);
-    }
-    return formatIsoTimestamp(millis);
-}
-function formatIsoTimestamp(millis) {
-    const iso = new Date(millis).toISOString();
-    return iso.endsWith('.000Z') ? `${iso.slice(0, -5)}Z` : iso;
-}
-/** Adds an ISO-8601 duration (`P30D`, `P1M`, `PT12H`, ...) to a timestamp, in UTC calendar units. */
-export function addIsoDuration(at, duration) {
-    const match = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/u
-        .exec(duration);
-    if (match === null || duration === 'P' || duration === 'PT') {
-        throw new TypeError(`Invalid ISO-8601 duration: ${duration}`);
-    }
-    const [, years, months, weeks, days, hours, minutes, seconds] = match;
-    const date = new Date(normalizeIsoTimestamp(at));
-    date.setUTCFullYear(date.getUTCFullYear() + Number(years ?? 0), date.getUTCMonth() + Number(months ?? 0), date.getUTCDate() + Number(weeks ?? 0) * 7 + Number(days ?? 0));
-    date.setUTCHours(date.getUTCHours() + Number(hours ?? 0), date.getUTCMinutes() + Number(minutes ?? 0), date.getUTCSeconds() + Number(seconds ?? 0));
-    return formatIsoTimestamp(date.getTime());
-}
 // Capabilities and fixture filling.
 /** Capabilities of a vector profile: omitted blocks default to all supported and `available`. */
 export function createCommerceConformanceCapabilities(profile) {
@@ -137,6 +119,10 @@ export function createCommerceConformanceStore(input) {
     let purchaseUiOpened = 0;
     let restoreCalls = 0;
     const emit = (event) => {
+        // An event-less store reports nothing; the reconciler polls its available list instead.
+        if (!capabilities.lifecycle.events) {
+            return;
+        }
         if (listener === undefined) {
             buffer.push(event);
             return;
@@ -283,12 +269,16 @@ function matchesFetchProducts(entry, request) {
  * 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.
+ * grant and a host-pushed grant never create a second entry. With
+ * `finalizeOnReread`, a replayed granted key is answered as finalized from
+ * the backend's own state.
  */
 export function createCommerceConformanceBackend(input = {}) {
     const decisions = [];
     const verifyRequests = [];
     const ledger = [];
+    /** Ledger entry id per granted idempotency key. */
+    const grants = new Map();
     const findEntry = (entryId) => ledger.find((entry) => entry.entryId === entryId);
     const reversalOf = (ledgerEntryId) => ledger.find((entry) => entry.type === 'revoke' && entry.reverses === ledgerEntryId);
     return {
@@ -303,6 +293,26 @@ export function createCommerceConformanceBackend(input = {}) {
         },
         async verifyPurchase(request) {
             verifyRequests.push(request);
+            const granted = grants.get(request.idempotencyKey);
+            if (granted !== undefined
+                && reversalOf(granted) === undefined
+                && input.finalizeOnReread?.() === true) {
+                // The key's own grant answers the re-read: no queued decision is
+                // consumed, so a decision scripted for another record stays in place.
+                // A reversed grant is not finalized; the re-read falls through to the script.
+                await input.finalize?.({
+                    store: request.store,
+                    transactionId: request.transactionId,
+                    ledgerEntryId: granted,
+                    logicalId: request.logicalId,
+                });
+                return {
+                    status: 'granted',
+                    ledgerEntryId: granted,
+                    finalization: 'completed',
+                    alreadyProcessed: true,
+                };
+            }
             const decision = decisions.shift();
             if (decision === undefined) {
                 throw new CommerceConformanceScriptError(`Unscripted verify for ${request.idempotencyKey} (${request.store}/${request.transactionId}); `
@@ -325,6 +335,7 @@ export function createCommerceConformanceBackend(input = {}) {
                     idempotencyKey: request.idempotencyKey,
                 });
             }
+            grants.set(request.idempotencyKey, ledgerEntryId);
             if (decision.finalization === 'completed') {
                 await input.finalize?.({
                     store: request.store,
@@ -726,6 +737,14 @@ export function createCommerceConformanceRuntime(input) {
     };
     const pass = async () => {
         const capabilities = await provider.getCapabilities();
+        // A provider without lifecycle.events is polled: every pass reads its available purchases.
+        if (!capabilities.lifecycle.events && capabilities.lifecycle.availablePurchases) {
+            for (const purchase of await provider.getAvailablePurchases({
+                includePending: capabilities.lifecycle.pending,
+            })) {
+                inbox.push({ type: 'purchaseUpdated', purchase });
+            }
+        }
         for (const event of inbox.splice(0, inbox.length)) {
             if (event.type === 'purchaseUpdated') {
                 await ingestPurchase(event.purchase);
@@ -787,7 +806,8 @@ export function createCommerceConformanceRuntime(input) {
             // Subscribe first, then read: an event delivered before the listener is found either way.
             unsubscribe = provider.subscribe(listener);
             const capabilities = await provider.getCapabilities();
-            if (capabilities.lifecycle.availablePurchases) {
+            // An event-less provider is polled by the first pass instead, so it is read once.
+            if (capabilities.lifecycle.availablePurchases && capabilities.lifecycle.events) {
                 for (const purchase of await provider.getAvailablePurchases({
                     includePending: capabilities.lifecycle.pending,
                 })) {
@@ -932,361 +952,76 @@ export function createCommerceConformanceRuntime(input) {
     };
 }
 /**
- * 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.
+ * The reference wallet (`createInMemoryCreditWallet`) on the vector clock,
+ * with the actor surface: fixture lots credit through `creditFromGrant`, the
+ * backend finalizer redeems through `finalize`, and owner-side mistakes in a
+ * vector surface as script errors.
  */
 export function createCommerceConformanceWallet(input) {
-    const { clock, store } = input;
-    const currencies = new Set(input.currencies);
-    const lots = [];
-    const spends = new Map();
-    const debits = [];
-    const entitlements = [];
-    const subscriptions = new Map();
-    const subscriptionEvents = [];
-    const listeners = new Set();
-    const buffer = createCommerceEventBuffer();
-    const snapshotLot = (lot) => ({ ...lot });
-    const toEntitlement = (entitlement) => ({
-        entitlementId: entitlement.entitlementId,
-        titleId: entitlement.titleId,
-        logicalId: entitlement.logicalId,
-        idempotencyKey: entitlement.idempotencyKey,
-        createdAt: entitlement.createdAt,
-        debits: [...entitlement.debits],
-    });
-    const toActiveSubscription = (subscription) => ({
-        store,
-        logicalId: subscription.logicalId,
-        subscriptionId: subscription.subscriptionId,
-        periodIndex: subscription.periodIndex,
-        state: subscription.state,
-        startedAt: subscription.startedAt,
-        expiresAt: subscription.expiresAt,
-        autoRenew: subscription.state === 'active',
+    const { clock } = input;
+    const wallet = createInMemoryCreditWallet({
+        store: input.store,
+        currencies: input.currencies,
+        now: () => clock.now(),
+        ...(input.offers === undefined ? {} : { offers: input.offers }),
     });
-    const emitSubscription = (subscription, type, periodIndex, reason) => {
-        const eventId = `${subscription.subscriptionId}:${periodIndex}:${type}`;
-        if (subscriptionEvents.some((event) => event.eventId === eventId)) {
-            return;
-        }
-        subscriptionEvents.push({
-            eventId,
-            type,
-            subscriptionId: subscription.subscriptionId,
-            logicalId: subscription.logicalId,
-            periodIndex,
-            expiresAt: subscription.expiresAt,
-            ...(reason === undefined ? {} : { reason }),
-        });
-        const event = {
-            type: 'subscriptionUpdated',
-            subscription: toActiveSubscription(subscription),
-        };
-        if (listeners.size === 0) {
-            buffer.push(event);
-            return;
-        }
-        for (const listener of listeners) {
-            listener(event);
-        }
-    };
-    const eligibleLots = (titleId, currency, scope) => {
-        const now = Date.parse(clock.now());
-        return lots
-            .filter((lot) => lot.currency === currency
-            && lot.remaining > 0
-            && (lot.expiresAt === undefined || Date.parse(lot.expiresAt) > now)
-            && (lot.spendScope.kind === 'cross-title'
-                || (scope === 'title' && lot.spendScope.titleId === titleId)))
-            .sort(compareCreditLotSpendOrder);
-    };
-    const spendScoped = async (request, scope) => {
-        const replay = spends.get(request.idempotencyKey);
-        if (replay !== undefined) {
-            return {
-                status: 'debited',
-                entitlementId: replay.entitlementId,
-                debits: [...replay.debits],
-                alreadyProcessed: true,
-            };
-        }
-        if (!currencies.has(request.currency)) {
-            return {
-                status: 'rejected',
-                error: {
-                    code: 'ITEM_UNAVAILABLE',
-                    retryable: false,
-                    message: `Currency ${request.currency} is not declared by the wallet.`,
-                },
-            };
-        }
-        if (!(request.amount > 0)) {
-            return {
-                status: 'rejected',
-                error: {
-                    code: 'INVALID_RESPONSE',
-                    retryable: false,
-                    message: 'Spend amount must be positive.',
-                },
-            };
-        }
-        const candidates = eligibleLots(request.titleId, request.currency, scope);
-        const available = candidates.reduce((sum, lot) => sum + lot.remaining, 0);
-        if (available < request.amount) {
-            return {
-                status: 'rejected',
-                error: {
-                    code: 'INSUFFICIENT_BALANCE',
-                    retryable: false,
-                    message: `Eligible ${request.currency} balance ${available} cannot cover ${request.amount}.`,
-                },
-            };
-        }
-        const spent = [];
-        let remaining = request.amount;
-        for (const lot of candidates) {
-            if (remaining <= 0) {
-                break;
-            }
-            const amount = Math.min(lot.remaining, remaining);
-            lot.remaining -= amount;
-            remaining -= amount;
-            spent.push({ lotId: lot.lotId, amount });
-            debits.push({ idempotencyKey: request.idempotencyKey, lotId: lot.lotId, amount });
-        }
-        const entitlementId = request.idempotencyKey;
-        spends.set(request.idempotencyKey, { entitlementId, debits: spent });
-        if (request.logicalId !== undefined) {
-            entitlements.push({
-                entitlementId,
-                titleId: request.titleId,
-                logicalId: request.logicalId,
-                idempotencyKey: request.idempotencyKey,
-                createdAt: clock.now(),
-                debits: [...spent],
-                redeemed: false,
-            });
-        }
-        return { status: 'debited', entitlementId, debits: [...spent] };
-    };
-    const renew = async (subscription) => {
-        while (subscription.state === 'active' && Date.parse(subscription.expiresAt) <= Date.parse(clock.now())) {
-            const nextPeriod = subscription.periodIndex + 1;
-            const result = await spendScoped({
-                titleId: subscription.titleId,
-                currency: subscription.terms.price.currency,
-                amount: subscription.terms.price.amount,
-                idempotencyKey: `membership:${subscription.subscriptionId}:${nextPeriod}`,
-            }, subscription.terms.scope);
-            if (result.status === 'rejected') {
-                subscription.state = 'lapsed';
-                emitSubscription(subscription, 'subscriptionLapsed', nextPeriod, result.error.code);
-                return;
-            }
-            subscription.periodIndex = nextPeriod;
-            subscription.expiresAt = addIsoDuration(subscription.expiresAt, subscription.terms.period);
-            emitSubscription(subscription, 'subscriptionRenewed', nextPeriod);
-        }
-    };
     return {
-        store,
+        store: wallet.store,
         get lots() {
-            return lots.map(snapshotLot);
+            return wallet.lots;
         },
         get debits() {
-            return [...debits];
+            return wallet.debits;
         },
         get entitlements() {
-            return entitlements.map(toEntitlement);
+            return wallet.entitlements;
         },
         get subscriptionEvents() {
-            return [...subscriptionEvents];
+            return wallet.subscriptionEvents;
         },
-        creditFromGrant(fixture, options = {}) {
-            const existing = lots.find((lot) => lot.lotId === fixture.ledgerEntryId);
-            if (existing !== undefined) {
-                return snapshotLot(existing);
-            }
-            if (!currencies.has(fixture.currency)) {
-                throw new CommerceConformanceScriptError(`Lot ${fixture.ledgerEntryId} uses currency ${fixture.currency}, which the wallet does not declare.`);
-            }
-            const lot = {
-                lotId: fixture.ledgerEntryId,
-                currency: fixture.currency,
-                amount: fixture.amount,
-                remaining: fixture.amount,
-                createdAt: normalizeIsoTimestamp(fixture.createdAt),
-                ...(fixture.expiresAt === undefined
-                    ? {}
-                    : { expiresAt: normalizeIsoTimestamp(fixture.expiresAt) }),
-                origin: { ...fixture.origin },
-                spendScope: deriveCreditLotSpendScope(fixture.origin, options.spendScope),
-            };
-            lots.push(lot);
-            return snapshotLot(lot);
+        get offers() {
+            return wallet.offers;
         },
-        spend: (request) => spendScoped(request, 'title'),
-        async startMembership(request) {
-            const current = subscriptions.get(request.subscriptionId);
-            if (current !== undefined && current.state === 'active') {
-                return {
-                    status: 'started',
-                    subscription: toActiveSubscription(current),
-                    entitlementId: `membership:${request.subscriptionId}:0`,
-                };
-            }
-            // The terms are validated before any credit moves, so malformed terms never charge.
-            const startedAt = clock.now();
-            let expiresAt;
+        addOffers: (offers) => wallet.addOffers(offers),
+        creditFromGrant(fixture, options = {}) {
             try {
-                expiresAt = addIsoDuration(startedAt, request.terms.period);
-            }
-            catch {
-                return {
-                    status: 'rejected',
-                    error: {
-                        code: 'ITEM_UNAVAILABLE',
-                        retryable: false,
-                        message: `Membership period ${request.terms.period} is not an ISO-8601 duration.`,
-                    },
-                };
-            }
-            const result = await spendScoped({
-                titleId: request.titleId,
-                currency: request.terms.price.currency,
-                amount: request.terms.price.amount,
-                idempotencyKey: `membership:${request.subscriptionId}:0`,
-                logicalId: request.logicalId,
-            }, request.terms.scope);
-            if (result.status === 'rejected') {
-                return result;
-            }
-            const subscription = {
-                subscriptionId: request.subscriptionId,
-                titleId: request.titleId,
-                logicalId: request.logicalId,
-                terms: request.terms,
-                periodIndex: 0,
-                startedAt,
-                expiresAt,
-                state: 'active',
-            };
-            subscriptions.set(subscription.subscriptionId, subscription);
-            emitSubscription(subscription, 'subscriptionStarted', 0);
-            return {
-                status: 'started',
-                subscription: toActiveSubscription(subscription),
-                entitlementId: result.entitlementId,
-            };
-        },
-        async renewDue() {
-            for (const subscription of subscriptions.values()) {
-                await renew(subscription);
-            }
-        },
-        async listOffers() {
-            return [...(input.offers ?? [])];
-        },
-        async listUnredeemed(request) {
-            return entitlements
-                .filter((entitlement) => !entitlement.redeemed && entitlement.titleId === request.titleId)
-                .map(toEntitlement);
-        },
-        async redeem(request) {
-            const entitlement = entitlements.find((candidate) => candidate.entitlementId === request.entitlementId);
-            if (entitlement === undefined) {
-                return { redeemed: false };
-            }
-            entitlement.redeemed = true;
-            return { redeemed: true };
-        },
-        finalize(request) {
-            const entitlement = entitlements.find((candidate) => candidate.entitlementId === request.transactionId);
-            if (entitlement !== undefined) {
-                entitlement.redeemed = true;
+                return wallet.creditFromGrant(fixture, options.spendScope === undefined ? {} : { explicit: options.spendScope });
             }
-        },
-        async getBalance(request) {
-            const balances = {};
-            for (const currency of currencies) {
-                balances[currency] = eligibleLots(request.titleId, currency, 'title').reduce((sum, lot) => sum + lot.remaining, 0);
+            catch (error) {
+                throw new CommerceConformanceScriptError(describeError(error));
             }
-            return { titleId: request.titleId, balances };
         },
-        async getActiveSubscriptions() {
-            return [...subscriptions.values()]
-                .filter((subscription) => subscription.state === 'active')
-                .map(toActiveSubscription);
-        },
-        subscribe(listener) {
-            const first = listeners.size === 0;
-            listeners.add(listener);
-            if (first) {
-                buffer.drain(listener);
-            }
-            return () => {
-                listeners.delete(listener);
-            };
+        spend: (request) => wallet.spend(request),
+        startMembership: (request) => wallet.startMembership(request),
+        renewDue: () => wallet.renewDue(),
+        listOffers: (request) => wallet.listOffers(request),
+        listUnredeemed: (request) => wallet.listUnredeemed(request),
+        redeem: (request) => wallet.redeem(request),
+        async finalize(request) {
+            await wallet.redeem({
+                entitlementId: request.transactionId,
+                ledgerEntryId: request.ledgerEntryId,
+            });
         },
+        getBalance: (request) => wallet.getBalance(request),
+        getActiveSubscriptions: (request) => wallet.getActiveSubscriptions(request),
+        subscribe: (listener, request) => wallet.subscribe(listener, request),
     };
 }
-/** Store lots are title-scoped, off-store lots cross-title, promotion lots as issued (title by default). */
-export function deriveCreditLotSpendScope(origin, explicit) {
-    switch (origin.channel) {
-        case 'store':
-            return { kind: 'title', titleId: origin.titleId };
-        case 'off-store':
-            return { kind: 'cross-title' };
-        case 'promotion':
-            return explicit ?? { kind: 'title', titleId: origin.titleId };
-    }
-}
-/** RFC spend order: earliest `expiresAt` (none last), `title` before `cross-title`, oldest `createdAt`, then `lotId`. */
-export function compareCreditLotSpendOrder(left, right) {
-    const leftExpiry = left.expiresAt === undefined
-        ? Number.POSITIVE_INFINITY
-        : Date.parse(left.expiresAt);
-    const rightExpiry = right.expiresAt === undefined
-        ? Number.POSITIVE_INFINITY
-        : Date.parse(right.expiresAt);
-    if (leftExpiry !== rightExpiry) {
-        return leftExpiry < rightExpiry ? -1 : 1;
-    }
-    if (left.spendScope.kind !== right.spendScope.kind) {
-        return left.spendScope.kind === 'title' ? -1 : 1;
-    }
-    const createdDelta = Date.parse(left.createdAt) - Date.parse(right.createdAt);
-    if (createdDelta !== 0) {
-        return createdDelta < 0 ? -1 : 1;
-    }
-    return left.lotId < right.lotId ? -1 : left.lotId > right.lotId ? 1 : 0;
-}
 /**
- * `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`.
+ * `createCreditCommerceProvider` over the reference wallet with the vector
+ * profile as its capability block. A wallet that lists no offers has the
+ * vector catalog registered as its offers first (a fixture price of one unit
+ * of the first wallet currency for entries without membership terms), so the
+ * wallet prices every spend and starts memberships itself. Memberships exist
+ * only where the billing authority is `host`.
  */
 export function createCommerceConformanceWalletProvider(input) {
     const { wallet, catalog, titleId, clock } = input;
-    const store = input.profile.store;
-    const membershipsOffered = input.billingAuthority === 'host';
-    const defaultCurrency = input.currencies[0] ?? 'credits';
-    const capabilities = () => {
-        const base = createCommerceConformanceCapabilities(input.profile);
-        return {
-            ...base,
-            purchase: { ...base.purchase, subscription: base.purchase.subscription && membershipsOffered },
-        };
-    };
+    const defaultCurrency = input.currencies[0];
+    if (defaultCurrency === undefined) {
+        throw new CommerceConformanceScriptError('The wallet profile declares no currencies.');
+    }
     const toOffer = (entry) => ({
         logicalId: entry.logicalId,
         storeSku: entry.storeSku,
@@ -1297,112 +1032,23 @@ export function createCommerceConformanceWalletProvider(input) {
         price: entry.membership?.price ?? { currency: defaultCurrency, amount: 1 },
         ...(entry.membership === undefined ? {} : { membership: entry.membership }),
     });
-    /** The wallet's own offers decide availability and price; the catalog fills in only when it lists none. */
-    const listOffers = async () => {
-        const offers = await wallet.listOffers({ titleId });
-        return (offers.length === 0 ? catalog.map(toOffer) : offers).filter((offer) => offer.membership === undefined || membershipsOffered);
-    };
-    /** Quantities of purchases made through this provider, so re-listed entitlements keep them. */
-    const quantities = new Map();
-    const toPurchase = (offer, entitlementId, createdAt, quantity) => ({
-        store,
-        transactionId: entitlementId,
-        storeSku: offer.storeSku,
-        logicalId: offer.logicalId,
-        quantity,
-        state: 'purchased',
-        purchasedAt: createdAt,
-        token: entitlementId,
-        evidence: { schema: `fixture.${store}.entitlement.v1`, payload: { entitlementId } },
-        accountBinding: { kind: 'host-identity' },
-        settlement: { ledgerEntryId: entitlementId },
-    });
-    const unavailable = (message) => ({
-        outcome: 'failed',
-        error: new CommerceError('ITEM_UNAVAILABLE', { message }).toCommerceErrorInfo(),
-    });
-    return {
-        store,
-        async getCapabilities() {
-            return capabilities();
-        },
-        async fetchProducts(request) {
-            return (await listOffers())
-                .filter((offer) => matchesFetchProducts(offer, request))
-                .map((offer) => ({
-                logicalId: offer.logicalId,
-                store,
-                storeSku: offer.storeSku,
-                kind: offer.kind,
-                title: offer.title,
-                description: offer.description,
-                price: {
-                    formatted: `${offer.price.amount} ${offer.price.currency}`,
-                    currencyCode: offer.price.currency,
-                },
-            }));
-        },
-        async requestPurchase(request) {
-            const offer = (await listOffers()).find((candidate) => candidate.logicalId === request.logicalId);
-            if (offer === undefined) {
-                return unavailable(`The wallet offers no product ${request.logicalId}.`);
-            }
-            const quantity = request.quantity ?? 1;
-            if (quantity > 1 && !capabilities().purchase.quantity) {
-                return unavailable('The wallet does not support purchase quantities above 1.');
-            }
-            if (offer.membership !== undefined) {
-                if (quantity > 1) {
-                    return unavailable('A membership is purchased one period at a time.');
-                }
-                const started = await wallet.startMembership({
-                    subscriptionId: request.idempotencyKey,
-                    titleId,
-                    logicalId: offer.logicalId,
-                    terms: offer.membership,
-                });
-                if (started.status === 'rejected') {
-                    return { outcome: 'failed', error: started.error };
-                }
-                quantities.set(started.entitlementId, 1);
-                return {
-                    outcome: 'purchased',
-                    purchase: toPurchase(offer, started.entitlementId, started.subscription.startedAt, 1),
-                };
-            }
-            const spend = await wallet.spend({
-                titleId,
-                currency: offer.price.currency,
-                amount: offer.price.amount * quantity,
-                idempotencyKey: request.idempotencyKey,
-                logicalId: offer.logicalId,
-            });
-            if (spend.status === 'rejected') {
-                return { outcome: 'failed', error: spend.error };
-            }
-            quantities.set(spend.entitlementId, quantity);
-            return {
-                outcome: 'purchased',
-                purchase: toPurchase(offer, spend.entitlementId, clock.now(), quantity),
-            };
-        },
-        async getAvailablePurchases() {
-            const offers = await listOffers();
-            const unredeemed = await wallet.listUnredeemed({ titleId });
-            return unredeemed.flatMap((entitlement) => {
-                const offer = offers.find((candidate) => candidate.logicalId === entitlement.logicalId);
-                return offer === undefined
-                    ? []
-                    : [toPurchase(offer, entitlement.entitlementId, entitlement.createdAt, quantities.get(entitlement.entitlementId) ?? 1)];
-            });
-        },
-        async getActiveSubscriptions() {
-            return wallet.getActiveSubscriptions();
-        },
-        subscribe(listener) {
-            return wallet.subscribe(listener);
+    if (wallet.offers.length === 0) {
+        wallet.addOffers(catalog.map(toOffer));
+    }
+    const capabilities = createCommerceConformanceCapabilities(input.profile);
+    return createCreditCommerceProvider(wallet, {
+        titleId,
+        billingAuthority: input.billingAuthority,
+        currencies: input.currencies,
+        capabilities: {
+            purchase: capabilities.purchase,
+            catalog: capabilities.catalog,
+            lifecycle: capabilities.lifecycle,
+            authority: capabilities.authority,
+            availability: capabilities.availability,
         },
-    };
+        now: () => clock.now(),
+    });
 }
 export function createCommerceConformanceHarness(context) {
     if (context.vector.wallet === undefined) {
@@ -1430,31 +1076,153 @@ export function createCommerceConformanceHarness(context) {
  * 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.
+ *
+ * With `options.createProvider`, a vector flagged `profile.adaptive` is first
+ * checked against the provider's declared capabilities
+ * (`commerceConformanceAdaptiveSkipReason`) and then matched against
+ * expectations derived from a reference run under those capabilities
+ * (`deriveAdaptiveCommerceConformanceExpectation`). Duplicate detection needs
+ * the whole run set, so it applies through `runCommerceConformanceVectors`.
  */
 export async function runCommerceConformanceVector(vector, options = {}) {
-    const failures = [];
-    const playerId = options.playerId ?? commerceConformanceDefaultPlayerId;
-    const titleId = options.titleId ?? commerceConformanceDefaultTitleId;
+    return runVectorIn(vector, options, purchaseFinishFamilyOf([vector]));
+}
+export async function runCommerceConformanceVectors(vectors, options = {}) {
+    // The `purchase-<owner>-finish` family of this run is fixed up front; the
+    // canonical member per owner is then one lookup per vector.
+    const family = purchaseFinishFamilyOf(vectors);
+    const results = [];
+    for (const vector of vectors) {
+        results.push(await runVectorIn(vector, options, family));
+    }
+    return results;
+}
+async function runVectorIn(vector, options, family) {
+    const ids = {
+        playerId: options.playerId ?? commerceConformanceDefaultPlayerId,
+        titleId: options.titleId ?? commerceConformanceDefaultTitleId,
+    };
+    const failed = (failures) => ({ vector: vector.vector, status: 'failed', passed: false, failures });
+    const skipped = (reason) => ({ vector: vector.vector, status: 'skipped', passed: false, failures: [], reason });
+    // 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);
+    }
+    catch (error) {
+        return failed([
+            { path: 'harness', expected: 'createProvider resolves', actual: describeError(error) },
+        ]);
+    }
+    let expectation = vector.expect;
+    let adaptive;
+    let adaptation;
+    if (options.createProvider !== undefined && vector.profile.adaptive === true) {
+        let capabilities;
+        try {
+            capabilities = await execution.harness.provider.getCapabilities();
+        }
+        catch (error) {
+            return failed([
+                {
+                    path: 'capabilities',
+                    expected: 'provider.getCapabilities() resolves',
+                    actual: describeError(error),
+                },
+            ]);
+        }
+        const reason = adaptiveSkipReasonWith(vector, capabilities, family);
+        if (reason !== undefined) {
+            return skipped(reason);
+        }
+        const store = execution.harness.provider.store;
+        adaptation = adaptationFor(vector, capabilities);
+        // The reference run reports the tokens the provider under test reports.
+        const tokenOf = execution.harness.store?.tokenOf;
+        const tokenAdaptedVector = tokenOf === undefined
+            ? vector
+            : withStoreTokens(vector, (purchase) => tokenOf.call(execution.harness.store, purchase));
+        let reference;
+        try {
+            reference = await prepareExecution(referenceVectorFor(tokenAdaptedVector, store, capabilities), createCommerceConformanceHarness, ids);
+        }
+        catch (error) {
+            return failed([
+                {
+                    path: 'reference.harness',
+                    expected: 'reference harness builds',
+                    actual: describeError(error),
+                },
+            ]);
+        }
+        const referenceFailures = await executeSteps(reference, adaptation);
+        const referenceFailure = referenceFailures[0];
+        if (referenceFailure !== undefined) {
+            // The reference pieces cannot play the scenario under these capabilities,
+            // which is a property of the vector and the capability set, not of the
+            // provider under test; the step and its error are kept in the reason.
+            return skipped(`the reference run under the provider capabilities failed at ${referenceFailure.path}: `
+                + `expected ${String(referenceFailure.expected)}, got ${String(referenceFailure.actual)}`);
+        }
+        const derived = await deriveAdaptiveExpectation(tokenAdaptedVector, reference, store);
+        if (derived.reason !== undefined) {
+            return skipped(derived.reason);
+        }
+        expectation = derived.expect;
+        adaptive = {
+            store,
+            finish: capabilities.lifecycle.finish,
+            evidence: capabilities.authority.evidence,
+            expect: expectation,
+        };
+    }
+    const failures = await executeSteps(execution, adaptation);
+    if (failures.length > 0) {
+        return { ...failed(failures), ...(adaptive === undefined ? {} : { adaptive }) };
+    }
+    try {
+        await matchExpectations(expectation, { ...execution, failures });
+    }
+    catch (error) {
+        // A provider read that throws while expectations are evaluated is a failed
+        // run, never a rejected promise.
+        failures.push({
+            path: 'expect',
+            expected: 'expectations evaluate',
+            actual: describeError(error),
+        });
+    }
+    return {
+        vector: vector.vector,
+        status: failures.length === 0 ? 'passed' : 'failed',
+        passed: failures.length === 0,
+        failures,
+        ...(adaptive === undefined ? {} : { adaptive }),
+    };
+}
+async function prepareExecution(vector, createHarness, ids) {
     const clock = createCommerceConformanceClock();
     const journal = createCommerceConformanceJournal();
     const harnessRef = {};
+    const adaptation = { current: undefined };
     const backend = createCommerceConformanceBackend({
         finalize: async (request) => {
             await harnessRef.current?.store?.finalize?.(request);
             await harnessRef.current?.wallet?.finalize?.(request);
         },
+        finalizeOnReread: () => adaptation.current?.serverFinalization === true,
     });
     const context = {
         vector,
         profile: vector.profile,
         catalog: vector.catalog ?? [],
-        playerId,
-        titleId,
+        playerId: ids.playerId,
+        titleId: ids.titleId,
         clock,
         backend,
         journal,
     };
-    const harness = await (options.createProvider ?? createCommerceConformanceHarness)(context);
+    const harness = await createHarness(context);
     harnessRef.current = harness;
     const runtime = createCommerceConformanceRuntime({
         provider: harness.provider,
@@ -1462,32 +1230,330 @@ export async function runCommerceConformanceVector(vector, options = {}) {
         journal,
         clock,
         catalog: context.catalog,
-        playerId,
+        playerId: ids.playerId,
     });
-    for (const [index, step] of vector.steps.entries()) {
+    return { vector, harness, runtime, backend, journal, clock, adaptation };
+}
+/** Runs every step; a thrown step ends the run with a failure at that step. */
+async function executeSteps(execution, adaptation) {
+    const failures = [];
+    execution.adaptation.current = adaptation;
+    const context = { ...execution, failures };
+    for (const [index, step] of execution.vector.steps.entries()) {
         const path = `steps[${index}]`;
         try {
-            await runStep(step, path, { harness, runtime, backend, clock, failures });
-            await runtime.runUntilIdle();
+            await runStep(step, path, context);
+            await execution.runtime.runUntilIdle();
         }
         catch (error) {
             failures.push({
                 path,
                 expected: `${step.actor}.${step.action} completes`,
-                actual: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+                actual: describeError(error),
             });
-            return { vector: vector.vector, passed: false, failures };
+            break;
         }
     }
-    await matchExpectations(vector, { harness, runtime, backend, journal, failures });
-    return { vector: vector.vector, passed: failures.length === 0, failures };
+    return failures;
 }
-export async function runCommerceConformanceVectors(vectors, options = {}) {
-    const results = [];
-    for (const vector of vectors) {
-        results.push(await runCommerceConformanceVector(vector, options));
+function describeError(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+// Adaptive vectors (RFC "Conformance vectors", adaptive vectors).
+/**
+ * Members of the `purchase-<owner>-finish` family describe the same purchase
+ * under different fixture finish owners; a provider runs the one named after
+ * its own owner, or the first by name when none is (`finish: 'none'`).
+ */
+const purchaseFinishFamily = /^purchase-(?:client|server|host|none)-finish$/u;
+export function isAdaptiveCommerceConformanceVector(vector) {
+    return vector.profile.adaptive === true;
+}
+/**
+ * Why an adaptive vector does not apply to a provider with `capabilities`, or
+ * `undefined` when it runs. `set` is the whole run (for duplicate detection).
+ * The rules:
+ *
+ * - a `game.requestPurchase` of a product kind the provider does not sell
+ *   (`purchase.<kind>` false, by the vector catalog), or with a quantity above
+ *   one without `purchase.quantity`, cannot open the store UI;
+ * - a store-side `pending` purchase needs `lifecycle.pending`;
+ * - a store `error` event needs `lifecycle.events`;
+ * - without `lifecycle.events`, a store `complete` or `update` reaches the
+ *   reconciler only by polling, so the next `runtime` step after it must be
+ *   `reconcile` or `start`;
+ * - a `queueFinish` script needs a `client` or `host` finish owner, since the
+ *   provider never calls `finishTransaction` under `server` or `none`;
+ * - within the `purchase-<owner>-finish` family only one member runs: the
+ *   one named after the provider's owner, else the first by name.
+ */
+export function commerceConformanceAdaptiveSkipReason(vector, capabilities, set = [vector]) {
+    return adaptiveSkipReasonWith(vector, capabilities, purchaseFinishFamilyOf(set));
+}
+function adaptiveSkipReasonWith(vector, capabilities, family) {
+    const stepReason = stepSkipReason(vector, capabilities);
+    if (stepReason !== undefined) {
+        return stepReason;
     }
-    return results;
+    if (purchaseFinishFamily.test(vector.vector)) {
+        const owner = capabilities.lifecycle.finish;
+        // The canonical member must itself be runnable here, so a provider whose
+        // capabilities rule out the member named after its owner still runs one.
+        const runnable = family.filter((member) => stepSkipReason(member, capabilities) === undefined);
+        const named = runnable.find((member) => member.vector === `purchase-${owner}-finish`);
+        const canonical = (named ?? runnable[0])?.vector;
+        if (canonical !== undefined && canonical !== vector.vector) {
+            return `duplicate of ${canonical} for finish='${owner}'`;
+        }
+    }
+    return undefined;
+}
+/** The step-level rules of `commerceConformanceAdaptiveSkipReason`, without the family rule. */
+function stepSkipReason(vector, capabilities) {
+    const { lifecycle, purchase } = capabilities;
+    const owner = lifecycle.finish;
+    const catalog = vector.catalog ?? [];
+    const steps = vector.steps;
+    for (const [index, step] of steps.entries()) {
+        if (step.actor === 'game' && step.action === 'requestPurchase') {
+            const kind = catalog.find((entry) => entry.logicalId === step.input.logicalId)?.kind;
+            if (kind !== undefined && !purchase[kind]) {
+                return `requestPurchase of ${step.input.logicalId} needs purchase.${kind}; `
+                    + `the provider declares ${kind}: false`;
+            }
+            const quantity = step.input.quantity ?? 1;
+            if (quantity > 1 && !purchase.quantity) {
+                return `requestPurchase of ${step.input.logicalId} with quantity ${String(quantity)} needs `
+                    + 'purchase.quantity; the provider declares quantity: false';
+            }
+            continue;
+        }
+        if (step.actor !== 'store') {
+            continue;
+        }
+        if (!lifecycle.pending
+            && ((step.action === 'complete' || step.action === 'update') && step.purchase.state === 'pending'
+                || (step.action === 'queueRequest'
+                    && step.result.outcome === 'purchased'
+                    && step.result.purchase.state === 'pending'))) {
+            return 'store-side pending purchase needs lifecycle.pending; the provider declares pending: false';
+        }
+        if (step.action === 'error' && !lifecycle.events) {
+            return 'purchaseError event needs lifecycle.events; the provider declares events: false';
+        }
+        if ((step.action === 'complete' || step.action === 'update') && !lifecycle.events) {
+            // Polling ingests the purchase at the next reconcile or start; a step in
+            // between that would have observed the event-driven grant or finish
+            // (another store script, a ledger write) makes the scenario timing-bound.
+            const prefix = `store.${step.action} at steps[${String(index)}] needs lifecycle.events; `
+                + 'the provider declares events: false';
+            if (!lifecycle.availablePurchases) {
+                return `${prefix} and lifecycle.availablePurchases: false, so nothing can poll the purchase`;
+            }
+            let polled = false;
+            for (const [offset, later] of steps.slice(index + 1).entries()) {
+                if (later.actor === 'runtime') {
+                    if (later.action === 'stop') {
+                        break;
+                    }
+                    polled = true;
+                    break;
+                }
+                if (later.actor === 'clock' || (later.actor === 'backend' && later.action === 'queueVerify')) {
+                    continue;
+                }
+                return `${prefix} and ${later.actor}.${later.action} at steps[${String(index + 1 + offset)}] `
+                    + 'runs before the reconcile or start that would poll the purchase';
+            }
+            if (!polled) {
+                return `${prefix} and no reconcile or start follows it to poll the purchase`;
+            }
+        }
+        if (step.action === 'queueFinish' && owner !== 'client' && owner !== 'host') {
+            return `queueFinish scripts a client finish; the provider declares finish: '${owner}'`;
+        }
+    }
+    return undefined;
+}
+/** The adaptive `purchase-<owner>-finish` members of a run, sorted by name. */
+function purchaseFinishFamilyOf(set) {
+    return set
+        .filter((candidate) => candidate.profile.adaptive === true && purchaseFinishFamily.test(candidate.vector))
+        .sort((left, right) => (left.vector < right.vector ? -1 : left.vector > right.vector ? 1 : 0));
+}
+function adaptationFor(vector, capabilities) {
+    const fixtureOwner = createCommerceConformanceCapabilities(vector.profile).lifecycle.finish;
+    return {
+        serverFinalization: capabilities.lifecycle.finish === 'server' && fixtureOwner !== 'server',
+    };
+}
+/**
+ * The vector with every scripted store purchase (`complete`, `update`, and a
+ * `queueRequest` answering `purchased`) carrying the token the store actor
+ * reports for it (`CommerceConformanceStoreActor.tokenOf`).
+ */
+export function withStoreTokens(vector, tokenOf) {
+    const withToken = (purchase) => ({ ...purchase, token: tokenOf(purchase) });
+    return {
+        ...vector,
+        steps: vector.steps.map((step) => {
+            if (step.actor !== 'store') {
+                return step;
+            }
+            if (step.action === 'complete' || step.action === 'update') {
+                return { ...step, purchase: withToken(step.purchase) };
+            }
+            if (step.action === 'queueRequest' && step.result.outcome === 'purchased') {
+                return { ...step, result: { ...step.result, purchase: withToken(step.result.purchase) } };
+            }
+            return step;
+        }),
+    };
+}
+/** The vector with the provider's store id and declared capabilities as its profile. */
+function referenceVectorFor(vector, store, capabilities) {
+    return {
+        ...vector,
+        profile: {
+            store,
+            purchase: capabilities.purchase,
+            lifecycle: capabilities.lifecycle,
+            authority: capabilities.authority,
+            adaptive: true,
+        },
+    };
+}
+/**
+ * Derives the adaptive expectation for `vector` from the observable state of a
+ * finished reference run under the provider's capabilities, applying the
+ * rules the RFC table states:
+ *
+ * - `journal`: the reference journal, so the tail after `granted` is
+ *   `finishing, finished` for `client`, `host`, and `server` owners and
+ *   `finished` for `none`; derived keys carry the provider's store id;
+ * - `finishCalls`: the reference store's calls, `by` the owner for `client`
+ *   and `host`, none for `server` and `none`;
+ * - `verifyRequests`: the reference backend's log, with the finalization
+ *   re-read a `server` owner adds unless the grant already reported
+ *   `finalization: 'completed'`;
+ * - `available`: what the reference store still lists once idle, so empty
+ *   after a completed finish for `client`, `host`, and `server` owners.
+ *
+ * Fields the fixture does not assert stay unasserted. The derivation is
+ * refused (a skip reason) when the reference run does not end every journal
+ * key in the fixture's terminal state, since the scenario then depends on a
+ * capability the provider lacks.
+ */
+export async function deriveAdaptiveCommerceConformanceExpectation(vector, reference) {
+    const { expect } = vector;
+    if (expect.journal !== undefined) {
+        const adapted = new Map();
+        for (const fixtureKey of Object.keys(expect.journal)) {
+            adapted.set(fixtureKey, await adaptDerivedPurchaseKey(vector, fixtureKey, reference.store));
+        }
+        for (const [fixtureKey, states] of Object.entries(expect.journal)) {
+            const key = adapted.get(fixtureKey) ?? fixtureKey;
+            const terminal = states.at(-1);
+            const actual = reference.journal[key]?.at(-1);
+            if (actual !== terminal) {
+                return {
+                    reason: `the reference run under the provider capabilities ends ${key} in `
+                        + `'${String(actual)}', not '${String(terminal)}'`,
+                };
+            }
+        }
+        const expectedKeys = new Set(adapted.values());
+        const extra = Object.keys(reference.journal).filter((key) => !expectedKeys.has(key));
+        if (extra.length > 0) {
+            return {
+                reason: `the reference run under the provider capabilities journals ${extra.join(', ')}, `
+                    + 'which the vector does not expect',
+            };
+        }
+    }
+    return {
+        expect: {
+            ...expect,
+            ...(expect.journal === undefined ? {} : { journal: reference.journal }),
+            ...(expect.verifyRequests === undefined
+                ? {}
+                : {
+                    verifyRequests: reference.verifyRequests.map((request) => ({
+                        idempotencyKey: request.idempotencyKey,
+                        store: request.store,
+                        transactionId: request.transactionId,
+                        token: request.token,
+                    })),
+                }),
+            ...(expect.finishCalls === undefined ? {} : { finishCalls: reference.finishCalls }),
+            ...(expect.available === undefined
+                ? {}
+                : {
+                    available: reference.available.map((purchase) => ({
+                        transactionId: purchase.transactionId,
+                        storeSku: purchase.storeSku,
+                        state: purchase.state,
+                    })),
+                }),
+        },
+    };
+}
+/**
+ * A fixture journal key as the provider's store id derives it: only the
+ * encoded store segment of a `store:<store>:<transactionId>` key
+ * (`createDerivedPurchaseIdempotencyKey`) is replaced, so a transaction id
+ * that happens to contain the fixture store id is left alone. Game-chosen
+ * keys and store-specific key forms carry no such prefix and pass through.
+ */
+export function adaptDerivedPurchaseKeyStore(key, fixtureStore, providerStore) {
+    const fixturePrefix = `store:${encodeURIComponent(fixtureStore)}:`;
+    return key.startsWith(fixturePrefix)
+        ? `store:${encodeURIComponent(providerStore)}:${key.slice(fixturePrefix.length)}`
+        : key;
+}
+/**
+ * A fixture journal key as the provider's store id derives it. When the key is
+ * the derived key of a purchase the vector scripts under the fixture store, it
+ * is re-derived with `createDerivedPurchaseIdempotencyKey` for the provider
+ * store, which also covers the store-specific key forms (`google-play` token
+ * keys, `apps-in-toss:purchase:<id>`); otherwise only the generic
+ * `store:<store>:` prefix is swapped (`adaptDerivedPurchaseKeyStore`).
+ */
+export async function adaptDerivedPurchaseKey(vector, key, providerStore) {
+    const fixtureStore = vector.profile.store;
+    for (const purchase of scriptedPurchasesOf(vector)) {
+        const derive = (store) => createDerivedPurchaseIdempotencyKey({
+            store,
+            transactionId: purchase.transactionId,
+            token: purchase.token,
+        });
+        if (await derive(fixtureStore) === key) {
+            return derive(providerStore);
+        }
+    }
+    return adaptDerivedPurchaseKeyStore(key, fixtureStore, providerStore);
+}
+function scriptedPurchasesOf(vector) {
+    return vector.steps.flatMap((step) => {
+        if (step.actor !== 'store') {
+            return [];
+        }
+        if (step.action === 'complete' || step.action === 'update') {
+            return [step.purchase];
+        }
+        return step.action === 'queueRequest' && step.result.outcome === 'purchased'
+            ? [step.result.purchase]
+            : [];
+    });
+}
+async function deriveAdaptiveExpectation(vector, reference, store) {
+    return deriveAdaptiveCommerceConformanceExpectation(vector, {
+        store,
+        journal: reference.journal.snapshot(),
+        verifyRequests: reference.backend.verifyRequests,
+        finishCalls: reference.harness.store?.finishCalls ?? [],
+        available: await reference.harness.provider.getAvailablePurchases({ includePending: true }),
+    });
 }
 function storeActorOf(context, step) {
     if (context.harness.store === undefined) {
@@ -1604,8 +1670,7 @@ async function runStep(step, path, context) {
             return;
     }
 }
-async function matchExpectations(vector, context) {
-    const { expect } = vector;
+async function matchExpectations(expect, context) {
     const { failures, harness } = context;
     if (expect.journal !== undefined) {
         const actual = context.journal.snapshot();