@mpgd/platform 0.18.0 → 0.20.0

package/dist/commerce-conformance.d.ts

@@ -0,0 +1,518 @@
+import { type ActiveSubscription, type CommerceBillingAuthority, type CommerceCapabilities, type CommerceErrorCode, type CommerceErrorInfo, type CommerceEvent, type CommerceEvidenceAuthority, type CommerceFinishOwner, 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, CommerceConformanceExpectation, 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. 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 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>;
+  /**
+  * The `token` this store reports for a fixture purchase when it is not the
+  * fixture's own: a host-order store reports the transaction id (RFC "Client
+  * contract"). An adaptive run replays the fixture purchases with this token
+  * into the reference store, so the derived verify requests carry the token
+  * the provider under test reports. Absent, the fixture token is used.
+  */
+  tokenOf?(purchase: CommerceConformancePurchaseFixture): string;
+}
+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>;
+  /**
+  * When it returns true, a verify request that replays a key this backend
+  * already granted is a finalization re-read (the reference reconciler under a
+  * server-owned finish): it is answered `{ granted, ledgerEntryId,
+  * finalization: 'completed', alreadyProcessed: true }` from the backend's own
+  * grant state and runs the finalizer, consuming no queued decision. Read on
+  * every call, so the runner can decide it once the provider's capabilities
+  * are known.
+  */
+  readonly finalizeOnReread?: () => boolean;
+}
+/**
+* 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. With
+* `finalizeOnReread`, a replayed granted key is answered as finalized from
+* the backend's own state.
+*/
+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 type CommerceConformanceVectorStatus = 'passed' | 'failed' | 'skipped';
+/**
+* `CommerceConformanceExpectation` as the matcher consumes it: a derived
+* `finishCalls` list carries the store actor's own records, whose `result` may
+* also be `unfinished`.
+*/
+export interface CommerceConformanceResolvedExpectation extends Omit<CommerceConformanceExpectation, 'finishCalls'> {
+  readonly finishCalls?: readonly CommerceConformanceFinishCall[];
+}
+/** How an adaptive vector's expectations were derived for the provider under test. */
+export interface CommerceConformanceAdaptation {
+  /** The provider's store id; it replaces the fixture store id in derived keys and verify requests. */
+  readonly store: StoreId;
+  readonly finish: CommerceFinishOwner;
+  readonly evidence: CommerceEvidenceAuthority;
+  /** The expectation the vector was matched against. */
+  readonly expect: CommerceConformanceResolvedExpectation;
+}
+export interface CommerceConformanceVectorResult {
+  readonly vector: string;
+  /** `skipped` vectors did not run; `passed` is false and `reason` says why. */
+  readonly status: CommerceConformanceVectorStatus;
+  readonly passed: boolean;
+  readonly failures: readonly CommerceConformanceFailure[];
+  readonly reason?: string;
+  /** Present when the vector ran with adaptive expectations. */
+  readonly adaptive?: CommerceConformanceAdaptation;
+}
+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.
+*
+* 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 declare function runCommerceConformanceVector(vector: CommerceConformanceVector, options?: CommerceConformanceRunOptions): Promise<CommerceConformanceVectorResult>;
+export declare function runCommerceConformanceVectors(vectors: readonly CommerceConformanceVector[], options?: CommerceConformanceRunOptions): Promise<readonly CommerceConformanceVectorResult[]>;
+export declare function isAdaptiveCommerceConformanceVector(vector: CommerceConformanceVector): boolean;
+/**
+* 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 declare function commerceConformanceAdaptiveSkipReason(vector: CommerceConformanceVector, capabilities: CommerceCapabilities, set?: readonly CommerceConformanceVector[]): string | undefined;
+/**
+* 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 declare function withStoreTokens(vector: CommerceConformanceVector, tokenOf: (purchase: CommerceConformancePurchaseFixture) => string): CommerceConformanceVector;
+/**
+* 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 declare function deriveAdaptiveCommerceConformanceExpectation(vector: CommerceConformanceVector, reference: {
+  readonly store: StoreId;
+  readonly journal: Readonly<Record<string, readonly CommercePurchaseState[]>>;
+  readonly verifyRequests: readonly CommerceVerifyRequest[];
+  readonly finishCalls: readonly CommerceConformanceFinishCall[];
+  /** What the reference store still lists (pending included) once the run is idle. */
+  readonly available: readonly StorePurchase[];
+}): Promise<{
+  readonly expect: CommerceConformanceResolvedExpectation;
+  readonly reason?: undefined;
+} | {
+  readonly expect?: undefined;
+  readonly reason: string;
+}>;
+/**
+* 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 declare function adaptDerivedPurchaseKeyStore(key: string, fixtureStore: string, providerStore: string): string;
+/**
+* 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 declare function adaptDerivedPurchaseKey(vector: CommerceConformanceVector, key: string, providerStore: string): Promise<string>;
+/**
+* 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;