@mpgd/platform 0.20.0 → 0.22.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
@@ -32,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) {
@@ -974,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,
@@ -1339,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) {
@@ -1503,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([
@@ -1596,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 = {};
@@ -1620,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,4 +1,4 @@
-import type { CommerceCapabilities, LogicalProductId, PlatformEvidenceEnvelope, StarterLogicalProductId } from './index.js';
+import type { CommerceCapabilities, CommerceFinishOwner, LogicalProductId, PlatformEvidenceEnvelope, StarterLogicalProductId } from './index.js';
 /**
 * Commerce v2 client contract types (RFC "Client contract"). This module is
 * typia-free on purpose: `./index` references `CommerceProvider` for
@@ -199,7 +199,13 @@ export interface CommerceProvider {
   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 +225,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 {};