@voltro/plugin-economy 0.0.0-stage → 0.88.0

package/dist/iapRefunds.d.ts

@@ -0,0 +1,755 @@
+import { BrandedScheduleDefinition } from '@voltro/runtime';
+import { ColumnBuilder } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { DeclaredAccess } from '@voltro/protocol';
+import { Effect } from 'effect';
+import { EventDescriptor } from '@voltro/protocol';
+import { EventPublishContext } from '@voltro/runtime';
+import { FieldDefinitions } from '@voltro/database';
+import { InventorySqlService } from '@voltro/plugin-inventory/server';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { PreparedSqlMutation } from '@voltro/database/sql';
+import { SanctionsService } from '@voltro/plugin-sanctions/port';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { Table } from '@voltro/database';
+import { YieldableError } from 'effect/Cause';
+
+declare const acceptedCompletion: unique symbol;
+
+/** SQL-issued capability. A player reference or serialized object cannot authorize provider completion. */
+declare interface AcceptedIapCompletion {
+    readonly [acceptedCompletion]: true;
+    readonly orderId: string;
+}
+
+/** Read-only SQL custody capability, never current provider state or refund authority. */
+declare interface AcceptedIapNotificationTarget {
+    readonly [acceptedNotificationTarget]: true;
+    readonly orderId: string;
+    readonly noticeId: string;
+}
+
+declare const acceptedNotificationTarget: unique symbol;
+
+export declare const captureIapRefundService: (input: IapRefundService) => IapRefundService;
+
+declare interface CurrencyDefinition {
+    readonly id: string;
+    readonly kind: 'soft' | 'hard';
+    readonly cap?: EconomyAmountInput;
+    readonly premium?: boolean;
+    readonly display?: {
+        readonly nameKey: string;
+    } | null;
+}
+
+export declare const dataStoreIapRefunds: (store: DataStore, input: IapRefundOptions) => IapRefundSqlService;
+
+/** SQL pending history survives process loss. Signals are idempotent; publication may repeat before acknowledgement. */
+export declare const deliverIapRefundEvents: (input: IapRefundEventDeliveryOptions) => Effect.Effect<IapRefundEventDeliveryResult, EconomyError>;
+
+declare type EconomyAccount = {
+    readonly kind: 'wallet';
+    readonly ownerId: string;
+    readonly ownerKind: WalletOwnerKind;
+} | {
+    readonly kind: 'system';
+    readonly id: string;
+};
+
+declare type EconomyAmountInput = string | number | bigint;
+
+declare type EconomyChannel = 'web' | 'ios' | 'android' | 'steam';
+
+/** Redacted codes; never carries owners, amounts or provider payloads. */
+declare class EconomyError extends EconomyError_base {
+}
+
+declare const EconomyError_base: Schema.Class<EconomyError, Schema.TaggedStruct<"EconomyError", {
+    readonly code: Schema.Literals<readonly ["invalid_currency", "invalid_amount", "overflow", "invalid_price", "real_money_disabled", "invalid_input", "invalid_record", "currency_cap_reached", "insufficient_funds", "conflict", "forbidden", "unavailable", "not_found", "erased", "limit_exceeded", "already_redeemed"]>;
+}>, YieldableError>;
+
+declare interface EconomyReceipt {
+    readonly txId: string;
+    readonly currency: string;
+    readonly amount: string;
+    readonly at: number;
+}
+
+declare interface EconomyReference {
+    readonly kind: string;
+    readonly id: string;
+}
+
+/** Guarded server-produced metadata. Ephemeral listeners are not the durable SQL audience. */
+export declare const economyRefunded: EventDescriptor<"economy.refunded", Schema.Struct<{
+    readonly subjectId: Schema.String;
+}>, Schema.Struct<{
+    readonly eventId: Schema.String;
+    readonly orderId: Schema.String;
+    readonly sequence: Schema.Number;
+    readonly state: Schema.Literals<readonly ["active", "partially-refunded", "revoked"]>;
+    readonly refundNumerator: Schema.Number;
+    readonly refundDenominator: Schema.Number;
+    readonly observedAt: Schema.Number;
+}>, DeclaredAccess<{
+    readonly subjectId: string;
+}>>;
+
+export declare const economyRefundReversed: EventDescriptor<"economy.refundReversed", Schema.Struct<{
+    readonly subjectId: Schema.String;
+}>, Schema.Struct<{
+    readonly eventId: Schema.String;
+    readonly orderId: Schema.String;
+    readonly sequence: Schema.Number;
+    readonly state: Schema.Literals<readonly ["active", "partially-refunded", "revoked"]>;
+    readonly refundNumerator: Schema.Number;
+    readonly refundDenominator: Schema.Number;
+    readonly observedAt: Schema.Number;
+}>, DeclaredAccess<{
+    readonly subjectId: string;
+}>>;
+
+declare interface EconomyService {
+    /** Trusted server transfer, never a player-authored value mutation. */
+    readonly transfer: (subject: Subject, input: LedgerTransferInput) => Effect.Effect<EconomyReceipt, EconomyError>;
+    readonly mine: (subject: Subject) => Effect.Effect<readonly EconomyWallet[], EconomyError>;
+    readonly auditWallet: (subject: Subject, tenantId: string, account: EconomyAccount, currency: string) => Effect.Effect<EconomyWalletAudit, EconomyError>;
+    readonly rebuildWallet: (subject: Subject, tenantId: string, account: EconomyAccount, currency: string) => Effect.Effect<EconomyWalletAudit, EconomyError>;
+}
+
+declare interface EconomySqlService extends EconomySystemService, WalletEscrowParticipant {
+    /** Trusted original purchase evidence required; no player price, owner or state authority. */
+    readonly prepareIapRefund: (subject: Subject, proof: VerifiedIapCurrentState, input: IapWalletRefundInput) => Effect.Effect<PreparedSqlMutation<EconomyReceipt>, EconomyError>;
+    readonly prepareTransfer: (subject: Subject, input: LedgerTransferInput) => Effect.Effect<PreparedSqlMutation<EconomyReceipt>, EconomyError>;
+}
+
+/** Full installed replacement adds both privacy hooks; the dependent port stays four methods. */
+declare interface EconomySystemService extends EconomyService {
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, EconomyError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, EconomyError>;
+}
+
+declare interface EconomyWallet {
+    readonly currency: string;
+    readonly balance: string;
+    readonly updatedAt: number | null;
+}
+
+declare interface EconomyWalletAudit {
+    readonly currency: string;
+    readonly balance: string;
+    readonly ledgerBalance: string;
+    readonly ledgerRows: number;
+    readonly matches: boolean;
+}
+
+declare type EscrowWallet = Extract<EconomyAccount, {
+    readonly kind: 'wallet';
+}>;
+
+declare interface IapCurrentPurchaseState {
+    readonly orderId: string;
+    readonly channel: IapRefundChannel;
+    readonly state: 'active' | 'partially-refunded' | 'revoked';
+    /** Exact cumulative provider refund share; never floating point or money sent by a player. */
+    readonly refundNumerator: number;
+    readonly refundDenominator: number;
+    readonly observedAt: number;
+    readonly revokedAt: number | null;
+}
+
+export declare type IapDebtPolicy = 'allowNegative' | 'blockSpend';
+
+declare type IapEnvironment = 'sandbox' | 'production';
+
+export declare interface IapInventoryRefundOptions {
+    readonly inventory: Pick<InventorySqlService, 'prepareConsume' | 'prepareGrant'>;
+    /** Explicit studio decision. Missing/traded/consumed items never count as recovered. */
+    readonly disposition: IapItemRefundDisposition;
+}
+
+export declare interface IapInventoryRefundReceipt {
+    readonly disposition: IapItemRefundDisposition;
+    readonly items: readonly ItemDisposition[];
+    readonly operations: readonly Movement[];
+    readonly targets: readonly number[];
+}
+
+export declare type IapItemRefundDisposition = 'requireAll' | 'recoverRemaining';
+
+declare interface IapNotificationTargetOptions {
+    readonly realMoney: boolean;
+    readonly channel: IapRefundChannel;
+    readonly applicationId: string;
+    readonly environment: IapEnvironment;
+}
+
+declare type IapOrderObservation = {
+    readonly requestId: string;
+    readonly state: 'not-observed' | 'pending';
+} | {
+    readonly requestId: string;
+    readonly state: 'fulfilled';
+    readonly receipt: IapOrderReceipt;
+    readonly refund?: IapRefundDisposition;
+} | {
+    readonly requestId: string;
+    readonly state: 'partially-refunded' | 'refunded';
+    readonly receipt: IapOrderReceipt;
+    readonly refund: IapRefundDisposition;
+};
+
+declare interface IapOrderReceipt {
+    readonly orderId: string;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly quantity: number;
+    readonly at: number;
+    readonly pricePaid: IapPaidAmount | null;
+    readonly transfers: readonly {
+        readonly txId: string;
+        readonly currency: string;
+        readonly amount: string;
+        readonly at: number;
+    }[];
+    readonly grants: readonly {
+        readonly operationId: string;
+        readonly kind: 'grant';
+        readonly changes: readonly {
+            readonly instanceId: string;
+            readonly delta: number;
+        }[];
+        readonly at: number;
+    }[];
+}
+
+/** Provider units retain their own decimal scale. Reference prices are never substituted. */
+declare interface IapPaidAmount {
+    readonly currency: string;
+    readonly units: string;
+    readonly scale: number;
+}
+
+declare interface IapProduct {
+    readonly offer: ShopOffer;
+    readonly channel: EconomyChannel;
+    readonly kind: IapProductKind;
+    readonly storeProductId: string;
+}
+
+declare type IapProductKind = 'consumable' | 'non-consumable' | 'subscription';
+
+declare interface IapReceiptIntent {
+    readonly channel: EconomyChannel;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly requestId: string;
+    /** Opaque store evidence. Never log or persist this in player receipts. */
+    readonly receipt: string;
+}
+
+/** Read-only original-intention reference. Never send raw receipts in query parameters. */
+declare interface IapReceiptReference {
+    readonly channel: EconomyChannel;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly requestId: string;
+    readonly receiptDigest: string;
+}
+
+export declare interface IapRefundAbuseDecision {
+    readonly confidence: number;
+}
+
+export declare type IapRefundAbusePolicy = (context: IapRefundEventContext) => IapRefundAbuseDecision | null;
+
+export declare const iapRefundAdjustmentsTable: Table<"_voltro_eco_iap_refund_adjustments", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKey: ColumnBuilder<string, "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly orderId: ColumnBuilder<string, "text", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+    readonly receipt: ColumnBuilder<unknown, "json", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly eventState: ColumnBuilder<string, "text", boolean>;
+    readonly eventDeliveryVersion: ColumnBuilder<string | null, "text", boolean>;
+}>, true, "voltro_eco_iap_refund_adjustments_owner_idx">;
+
+export declare interface IapRefundAssetContext {
+    readonly original: IapSqlOriginalPurchase;
+    readonly state: IapCurrentPurchaseState;
+    readonly previous: IapRefundReceipt | null;
+    readonly sequence: number;
+}
+
+/** Mandatory for orders with item grants. It must use the same real store and original grant custody. */
+export declare interface IapRefundAssetParticipant {
+    readonly prepare: (input: IapRefundAssetContext) => Effect.Effect<PreparedSqlMutation<unknown>, EconomyError>;
+    readonly validate: (input: IapRefundAssetContext, receipt: unknown) => unknown;
+    /** SQL-only audit of accepted movement receipts; no provider/application callbacks. */
+    readonly audit: (tx: DataStore, input: IapRefundAssetContext, receipt: unknown) => Promise<void>;
+}
+
+/** Channels whose providers report refunds and revocations to the economy. */
+declare type IapRefundChannel = 'ios' | 'android' | 'web';
+
+export declare interface IapRefundCurrency {
+    readonly currency: string;
+    readonly original: string;
+    readonly refunded: string;
+}
+
+/** Accepted SQL refund history only. This projection never authorizes a grant or completion. */
+declare interface IapRefundDisposition {
+    readonly sequence: number;
+    readonly state: 'active' | 'partially-refunded' | 'revoked';
+    readonly refundNumerator: number;
+    readonly refundDenominator: number;
+    readonly observedAt: number;
+}
+
+/** Borrowed transaction read only: no provider, nested transaction, seed, clock or mutation. */
+declare interface IapRefundDispositionSource {
+    readonly read: (tx: DataStore, original: IapSqlOriginalPurchase) => Promise<IapRefundDisposition | null>;
+}
+
+export declare interface IapRefundEventContext {
+    readonly namespace: string;
+    readonly tenantId: string;
+    readonly subjectId: string;
+    readonly payload: IapRefundEventPayload;
+    /** Complete bounded accepted history; these are observations, never a fraud verdict. */
+    readonly refundedOrders: number;
+    readonly observedOrders: number;
+    readonly refundAdjustments: number;
+}
+
+export declare interface IapRefundEventDeliveryOptions {
+    readonly events: IapRefundEventsService;
+    readonly publisher: IapRefundEventPublisherSource;
+    readonly version: string;
+    readonly maxEvents?: number | undefined;
+    readonly sanctions?: Pick<SanctionsService, 'recordSignal'> | undefined;
+    readonly abusePolicy?: IapRefundAbusePolicy | undefined;
+}
+
+export declare interface IapRefundEventDeliveryResult {
+    readonly scannedRows: number;
+    readonly deliveredEvents: number;
+    readonly classifiedSignals: number;
+}
+
+export declare type IapRefundEventPayload = typeof IapRefundEventPayloadSchema.Type;
+
+export declare const IapRefundEventPayloadSchema: Schema.Struct<{
+    readonly eventId: Schema.String;
+    readonly orderId: Schema.String;
+    readonly sequence: Schema.Number;
+    readonly state: Schema.Literals<readonly ["active", "partially-refunded", "revoked"]>;
+    readonly refundNumerator: Schema.Number;
+    readonly refundDenominator: Schema.Number;
+    readonly observedAt: Schema.Number;
+}>;
+
+export declare interface IapRefundEventPublisherSource {
+    /** Actual tenant-bound framework context, including its durable workflow audience when configured. */
+    readonly read: (tenantId: string) => Effect.Effect<EventPublishContext, EconomyError>;
+}
+
+/** Ordinary discovered schedule. It starts no timer and supplies no invented event bus or tenant. */
+export declare const iapRefundEventSchedule: (input: IapRefundEventScheduleOptions) => BrandedScheduleDefinition;
+
+export declare interface IapRefundEventScheduleOptions extends IapRefundEventDeliveryOptions {
+    readonly name: string;
+    readonly cron: string;
+    readonly timezone?: string;
+}
+
+export declare class IapRefundEventsPort extends IapRefundEventsPort_base {
+}
+
+declare const IapRefundEventsPort_base: Context.ServiceClass<IapRefundEventsPort, "@voltro/IapRefundEventsPort", IapRefundEventsService>;
+
+export declare interface IapRefundEventsService {
+    readonly pending: (subject: Subject) => Effect.Effect<readonly PendingIapRefundEvent[], EconomyError>;
+    readonly read: (subject: Subject, event: PendingIapRefundEvent) => Effect.Effect<IapRefundEventContext, EconomyError>;
+    readonly acknowledge: (subject: Subject, event: PendingIapRefundEvent, deliveryVersion: string) => Effect.Effect<void, EconomyError>;
+}
+
+export declare const iapRefundNamespacesTable: Table<"_voltro_eco_iap_refund_namespaces", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly configurationDigest: ColumnBuilder<string, "text", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>;
+
+export declare interface IapRefundOptions {
+    readonly realMoney: boolean;
+    readonly namespace: string;
+    readonly debtPolicy: IapDebtPolicy;
+    readonly orders: Pick<IapSqlService, 'prepareCurrentState'>;
+    readonly economy: Pick<EconomySqlService, 'prepareTransfer' | 'prepareIapRefund'>;
+    readonly assets?: IapRefundAssetParticipant | undefined;
+    readonly assetsVersion?: string | undefined;
+    readonly maxHistoryRows?: number | undefined;
+}
+
+export declare const iapRefundOrdersTable: Table<"_voltro_eco_iap_refund_orders", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKey: ColumnBuilder<string, "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly orderId: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly configurationDigest: ColumnBuilder<string, "text", boolean>;
+    readonly receipt: ColumnBuilder<unknown, "json", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, "voltro_eco_iap_refund_orders_owner_idx">;
+
+export declare class IapRefundPort extends IapRefundPort_base {
+}
+
+declare const IapRefundPort_base: Context.ServiceClass<IapRefundPort, "@voltro/IapRefundPort", IapRefundService>;
+
+export declare interface IapRefundReceipt {
+    readonly orderId: string;
+    readonly sequence: number;
+    readonly state: IapCurrentPurchaseState['state'];
+    readonly refundNumerator: number;
+    readonly refundDenominator: number;
+    readonly observedAt: number;
+    readonly noticeId: string;
+    readonly fingerprint: string;
+    readonly debtPolicy: IapDebtPolicy;
+    readonly currencies: readonly IapRefundCurrency[];
+    readonly transfers: readonly EconomyReceipt[];
+    /** Opaque actual asset participant receipt, validated by its captured participant. */
+    readonly assets: unknown;
+}
+
+export declare interface IapRefundService {
+    readonly reconcile: (proof: VerifiedIapCurrentState) => Effect.Effect<IapRefundReceipt, EconomyError>;
+    readonly rebuild: (proof: VerifiedIapCurrentState) => Effect.Effect<IapRefundReceipt | null, EconomyError>;
+    readonly observe: (scope: IapScope, orderId: string) => Effect.Effect<IapRefundReceipt | null, EconomyError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, EconomyError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, EconomyError>;
+}
+
+/** SQL remains refund history and rebuild source. External provider I/O is complete before this writer. */
+export declare interface IapRefundSqlService extends IapRefundService {
+    readonly events: IapRefundEventsService;
+    readonly readDisposition: IapRefundDispositionSource['read'];
+}
+
+export declare const iapRefundSubjectsTable: Table<"_voltro_eco_iap_refund_subjects", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>;
+
+export declare const iapRefundTables: readonly [ Table<"_voltro_eco_iap_refund_namespaces", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly configurationDigest: ColumnBuilder<string, "text", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>, Table<"_voltro_eco_iap_refund_subjects", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>, Table<"_voltro_eco_iap_refund_orders", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKey: ColumnBuilder<string, "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly orderId: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly configurationDigest: ColumnBuilder<string, "text", boolean>;
+    readonly receipt: ColumnBuilder<unknown, "json", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, "voltro_eco_iap_refund_orders_owner_idx">, Table<"_voltro_eco_iap_refund_adjustments", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKey: ColumnBuilder<string, "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly orderId: ColumnBuilder<string, "text", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+    readonly receipt: ColumnBuilder<unknown, "json", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly eventState: ColumnBuilder<string, "text", boolean>;
+    readonly eventDeliveryVersion: ColumnBuilder<string | null, "text", boolean>;
+}>, true, "voltro_eco_iap_refund_adjustments_owner_idx">];
+
+declare interface IapScope {
+    readonly tenantId: string;
+    readonly ownerId: string;
+}
+
+declare interface IapService {
+    readonly redeem: (subject: Subject, input: IapReceiptIntent) => Effect.Effect<IapOrderReceipt, EconomyError>;
+    readonly receipt: (subject: Subject, input: IapReceiptReference) => Effect.Effect<IapOrderObservation, EconomyError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, EconomyError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, EconomyError>;
+}
+
+/** SQL original after the owning adapter has validated its immutable custody and receipt. */
+declare interface IapSqlOriginalPurchase {
+    readonly orderId: string;
+    readonly scope: IapScope;
+    readonly receipt: IapOrderReceipt;
+    readonly product: IapProduct;
+    readonly facts: IapTransactionFacts;
+    readonly currencies: readonly CurrencyDefinition[];
+}
+
+declare interface IapSqlService extends IapService {
+    /** Complete owned accepted subscription periods. SQL reads only; never current provider status. */
+    readonly subscriptionPeriods: (subject: Subject) => Effect.Effect<readonly IapSubscriptionPeriod[], EconomyError>;
+    /** Server only: the provider's original transaction IDs (a Stripe subscription) of the owner's
+     * accepted subscription orders on `channel`, newest period first. Never a player projection. */
+    readonly subscriptionOriginals: (subject: Subject, channel: EconomyChannel) => Effect.Effect<readonly string[], EconomyError>;
+    /** Actual original IAP/account/retained-notice SQL fences; joins the same-store financial mutation group. */
+    readonly prepareCurrentState: (evidence: VerifiedIapCurrentState) => Effect.Effect<PreparedSqlMutation<IapCurrentPurchaseState>, EconomyError>;
+    /** Trusted server declaration + authenticated notice; read accepted SQL, never seed or fulfill. */
+    readonly prepareNotification: (options: IapNotificationTargetOptions, notice: VerifiedIapNotification) => Effect.Effect<AcceptedIapNotificationTarget, EconomyError>;
+    /** Read accepted SQL original and issue a revalidated capability; no grant, clock or provider call. */
+    readonly prepareCompletion: (subject: Subject, intent: Parameters<IapService['redeem']>[1]) => Effect.Effect<AcceptedIapCompletion, EconomyError>;
+}
+
+/** An accepted store period, not a fresh provider observation or financial capability. */
+declare interface IapSubscriptionPeriod {
+    readonly orderId: string;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly channel: EconomyChannel;
+    readonly startsAt: number;
+    readonly expiresAt: number;
+    readonly refund: IapRefundDisposition | null;
+}
+
+declare interface IapTransactionFacts {
+    readonly channel: EconomyChannel;
+    readonly environment: IapEnvironment;
+    readonly applicationId: string;
+    readonly transactionId: string;
+    readonly originalTransactionId: string | null;
+    readonly storeProductId: string;
+    readonly kind: IapProductKind;
+    readonly quantity: number;
+    readonly purchasedAt: number;
+    readonly expiresAt: number | null;
+    readonly paid: IapPaidAmount | null;
+    readonly acknowledgement: 'none' | 'pending' | 'acknowledged';
+    readonly consumption: 'none' | 'available' | 'consumed';
+}
+
+export declare interface IapWalletRefundInput {
+    readonly requestId: string;
+    readonly currency: string;
+    readonly amount: string;
+    readonly debtPolicy: IapDebtPolicy;
+}
+
+/** Same SQL inventory movement writer, original grant journal and receiver-captured participant. */
+export declare const inventoryIapRefundAssets: (store: DataStore, input: IapInventoryRefundOptions) => IapRefundAssetParticipant;
+
+declare interface ItemDisposition {
+    readonly grantId: string;
+    readonly instanceId: string;
+    readonly itemId: string;
+    readonly original: number;
+    readonly requested: number;
+    readonly recovered: number;
+    readonly unrecoverable: number;
+    readonly candidates: readonly string[];
+}
+
+declare interface LedgerTransferInput {
+    readonly tenantId: string;
+    readonly requestId: string;
+    readonly currency: string;
+    readonly from: EconomyAccount;
+    readonly to: EconomyAccount;
+    readonly amount: EconomyAmountInput;
+    readonly reason: string;
+    readonly ref: EconomyReference;
+}
+
+declare interface Movement {
+    readonly operationId: string;
+    readonly kind: 'consume' | 'grant';
+    readonly changes: readonly {
+        readonly instanceId: string;
+        readonly delta: number;
+    }[];
+    readonly at: number;
+}
+
+/** A refund observation alone establishes no abuse. Operators supply an actual classification policy. */
+export declare const noRefundAbuseSignal: IapRefundAbusePolicy;
+
+/** Actual pending SQL event authority. Copies and serialized payloads cannot authorize delivery acknowledgement. */
+export declare interface PendingIapRefundEvent {
+    readonly [refundEvent]: true;
+    readonly eventId: string;
+}
+
+declare type Price = {
+    readonly kind: 'virtual';
+    readonly options: readonly ResolvedVirtualPriceOption[];
+} | ({
+    readonly kind: 'real';
+} & RealPriceDefinition) | {
+    readonly kind: 'mixed';
+    readonly real: RealPriceDefinition;
+    readonly virtual: readonly ResolvedVirtualPriceOption[];
+} | {
+    readonly kind: 'free';
+};
+
+declare interface RealPriceDefinition {
+    /** Integer minor-unit references; verified store receipts remain authoritative. */
+    readonly prices: Readonly<Record<string, number>>;
+    readonly storeProductIds: Partial<Readonly<Record<EconomyChannel, string>>>;
+}
+
+declare const refundEvent: unique symbol;
+
+declare interface ResolvedVirtualPriceOption {
+    readonly currency: string;
+    readonly amount: string;
+}
+
+declare interface ShopItemGrant {
+    readonly itemId: string;
+    readonly qty: number;
+}
+
+declare interface ShopOffer {
+    readonly id: string;
+    readonly version: string;
+    readonly titleKey: string;
+    readonly price: Price;
+    readonly items: readonly ShopItemGrant[];
+    readonly currencies: readonly {
+        readonly currency: string;
+        readonly amount: string;
+    }[];
+    readonly from: number | null;
+    readonly until: number | null;
+    readonly segment: string | null;
+    readonly flag: string | null;
+    readonly countries: readonly string[];
+    readonly limits: {
+        readonly perPlayer: number | null;
+        readonly perDay: number | null;
+        readonly global: number | null;
+    };
+    readonly oneTime: boolean;
+    readonly maxQuantity: number;
+}
+
+declare const verifiedCurrentState: unique symbol;
+
+/** Fresh provider observation bound to revalidated original SQL. Never copied player refund authority. */
+declare interface VerifiedIapCurrentState {
+    readonly [verifiedCurrentState]: true;
+    readonly orderId: string;
+}
+
+/** Authenticated notice, never current purchase state or grant/refund authority. */
+declare interface VerifiedIapNotification {
+    readonly [verifiedNotification]: true;
+    readonly noticeId: string;
+    readonly channel: IapRefundChannel;
+}
+
+declare const verifiedNotification: unique symbol;
+
+declare interface WalletEscrowFundedSettlementReceipt {
+    readonly reserve: EconomyReceipt;
+    readonly settlement: WalletEscrowSettlementReceipt;
+}
+
+declare interface WalletEscrowInput {
+    readonly tenantId: string;
+    readonly owner: EscrowWallet;
+    readonly reservationId: string;
+    readonly currency: string;
+}
+
+declare type WalletEscrowObservation = {
+    readonly reservationId: string;
+    readonly currency: string;
+    readonly state: 'not-observed';
+} | {
+    readonly reservationId: string;
+    readonly currency: string;
+    readonly amount: string;
+    readonly state: 'held' | 'released' | 'settled';
+    readonly receipt: EconomyReceipt;
+    readonly closingReceipt: EconomyReceipt | null;
+    readonly taxReceipt: EconomyReceipt | null;
+};
+
+declare interface WalletEscrowParticipant {
+    readonly prepareEscrowReserve: (subject: Subject, input: WalletEscrowReserveInput) => Effect.Effect<PreparedSqlMutation<EconomyReceipt>, EconomyError>;
+    readonly prepareEscrowRelease: (subject: Subject, input: WalletEscrowInput) => Effect.Effect<PreparedSqlMutation<EconomyReceipt>, EconomyError>;
+    /** Whole gross payout; use prepareEscrowTaxSettle for an exact net/sink split. */
+    readonly prepareEscrowSettle: (subject: Subject, input: WalletEscrowSettleInput) => Effect.Effect<PreparedSqlMutation<EconomyReceipt>, EconomyError>;
+    readonly prepareEscrowTaxSettle: (subject: Subject, input: WalletEscrowTaxSettleInput) => Effect.Effect<PreparedSqlMutation<WalletEscrowSettlementReceipt>, EconomyError>;
+    readonly prepareEscrowReserveTaxSettle: (subject: Subject, input: WalletEscrowReserveTaxSettleInput) => Effect.Effect<PreparedSqlMutation<WalletEscrowFundedSettlementReceipt>, EconomyError>;
+    readonly escrow: (subject: Subject, input: WalletEscrowInput) => Effect.Effect<WalletEscrowObservation, EconomyError>;
+}
+
+declare interface WalletEscrowReserveInput extends WalletEscrowInput {
+    readonly amount: EconomyAmountInput;
+}
+
+declare interface WalletEscrowReserveTaxSettleInput extends WalletEscrowReserveInput {
+    readonly to: EscrowWallet;
+    readonly taxAmount: EconomyAmountInput;
+    readonly taxAccountId?: string | undefined;
+}
+
+declare interface WalletEscrowSettleInput extends WalletEscrowInput {
+    readonly to: EscrowWallet;
+}
+
+declare interface WalletEscrowSettlementReceipt {
+    readonly reservationId: string;
+    readonly currency: string;
+    readonly gross: string;
+    readonly net: string;
+    readonly tax: string;
+    readonly payout: EconomyReceipt | null;
+    readonly taxReceipt: EconomyReceipt | null;
+}
+
+declare interface WalletEscrowTaxSettleInput extends WalletEscrowSettleInput {
+    readonly taxAmount: EconomyAmountInput;
+    readonly taxAccountId?: string | undefined;
+}
+
+declare type WalletOwnerKind = 'player' | 'guild';
+
+export { }