@voltro/plugin-economy 0.0.0-stage → 0.88.0

package/dist/iapNotificationTarget.testFixtures.js

@@ -0,0 +1,29 @@
+import { issueVerifiedIapNotification as e } from "./iapNotifications.server.js";
+import { randomUUID as t } from "node:crypto";
+// src/iapNotificationTarget.testFixtures.ts
+var n = (n, r = {}) => {
+	let i = {
+		channel: "ios",
+		applicationId: n.verificationOptions.applicationId,
+		environment: "sandbox",
+		noticeId: t(),
+		sourceType: "REFUND",
+		kind: "voided",
+		occurredAt: n.at,
+		transactionId: n.transactionId,
+		originalTransactionId: n.facts.originalTransactionId,
+		storeProductId: n.facts.storeProductId,
+		...r
+	};
+	return {
+		notice: i,
+		options: {
+			realMoney: !0,
+			channel: "ios",
+			applicationId: n.verificationOptions.applicationId,
+			environment: "sandbox"
+		},
+		evidence: e(i, { privateReceipt: n.receipt })
+	};
+};
+export { n as iapSqlNoticeFixture };

package/dist/iapNotifications.d.ts

@@ -0,0 +1,644 @@
+import { BrandedScheduleDefinition } from '@voltro/runtime';
+import { ColumnBuilder } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { FieldCipher } from '@voltro/database';
+import { FieldDefinitions } from '@voltro/database';
+import { PluginHttpRoute } from '@voltro/protocol';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { PreparedSqlMutation } from '@voltro/database/sql';
+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 captureIapNotificationCustodyService: (input: IapNotificationCustodyService) => IapNotificationCustodyService;
+
+export declare const captureIapNotificationProcessorService: (input: IapNotificationProcessorService) => IapNotificationProcessorService;
+
+export declare const captureIapNotificationsSystemService: (input: IapNotificationsSystemService) => IapNotificationsSystemService;
+
+declare interface CurrencyDefinition {
+    readonly id: string;
+    readonly kind: 'soft' | 'hard';
+    readonly cap?: EconomyAmountInput;
+    readonly premium?: boolean;
+    readonly display?: {
+        readonly nameKey: string;
+    } | null;
+}
+
+/** Borrowed SQL with explicit framework cipher, full bounded scans and durable privacy/identity fences. */
+export declare const dataStoreIapNotificationCustody: (store: DataStore, input: IapNotificationCustodyOptions) => IapNotificationCustodyService;
+
+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 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;
+}
+
+declare interface IapCurrentStateService {
+    readonly initialize: () => Effect.Effect<void, EconomyError>;
+    readonly read: (target: AcceptedIapNotificationTarget) => Effect.Effect<VerifiedIapCurrentState, EconomyError>;
+}
+
+declare type IapDebtPolicy = 'allowNegative' | 'blockSpend';
+
+declare type IapEnvironment = 'sandbox' | 'production';
+
+export declare interface IapInstalledNotificationScheduleOptions {
+    readonly system: IapNotificationsSystemService;
+    readonly channel: EconomyChannel;
+    readonly name: string;
+    readonly cron: string;
+    readonly timezone?: string;
+    readonly maxNotices?: number;
+}
+
+export declare interface IapNotificationCipherSource {
+    /** Default is the registered framework FieldCipher. Explicit sources use that same codec/row binding contract. */
+    readonly read: () => FieldCipher | undefined;
+}
+
+export declare interface IapNotificationCustodyOptions {
+    readonly cipher?: IapNotificationCipherSource | undefined;
+    readonly namespace: string;
+    readonly deployment: IapNotificationTargetOptions;
+    readonly orders: Pick<IapSqlService, 'prepareNotification'>;
+    /** Explicit operator retention, never a guessed region/privacy policy. Expired identities cannot recreate payloads. */
+    readonly bodyRetentionMs: number;
+    readonly maxRows?: number;
+    readonly maxBodyBytes?: number;
+    readonly now?: (() => number) | undefined;
+}
+
+export declare class IapNotificationCustodyPort extends IapNotificationCustodyPort_base {
+}
+
+declare const IapNotificationCustodyPort_base: Context.ServiceClass<IapNotificationCustodyPort, "@voltro/IapNotificationCustodyPort", IapNotificationCustodyService>;
+
+export declare interface IapNotificationCustodyReceipt {
+    readonly id: string;
+    readonly orderId: string;
+    readonly state: 'pending' | 'processed' | 'expired' | 'erased';
+}
+
+export declare interface IapNotificationCustodyService {
+    readonly initialize: () => Effect.Effect<void, EconomyError>;
+    readonly retain: (evidence: VerifiedIapNotification) => Effect.Effect<IapNotificationCustodyReceipt, EconomyError>;
+    /** Trusted server worker, not a player RPC. Restores only row-bound authenticated SQL custody. */
+    readonly restore: (id: string) => Effect.Effect<VerifiedIapNotification, EconomyError>;
+    /** Actual accepted refund capability and same-store journal fence required. */
+    readonly markProcessed: (id: string, receipt: IapRefundReceipt) => Effect.Effect<IapNotificationCustodyReceipt, EconomyError>;
+    readonly pending: () => Effect.Effect<readonly IapNotificationCustodyReceipt[], EconomyError>;
+    readonly prune: () => Effect.Effect<number, EconomyError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, EconomyError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, EconomyError>;
+}
+
+export declare interface IapNotificationHttpOptions {
+    readonly path: string;
+    readonly maxBodyBytes: number;
+    readonly processor: IapNotificationProcessorService;
+    /** Provider-delivered purchases first; `true` answers the request without the notification pipeline. */
+    readonly deliver?: (input: IapNotificationInput) => Effect.Effect<boolean, EconomyError>;
+}
+
+/** A real plugin HTTP declaration, mounted by the normal API gateway; cookie/query/body status conveys no authority. */
+export declare const iapNotificationHttpRoute: (input: IapNotificationHttpOptions) => PluginHttpRoute;
+
+declare interface IapNotificationInput {
+    readonly body: string;
+    /** Actual HTTP Authorization header for authenticated Pub/Sub push; never query/body authority. */
+    readonly authorization?: string;
+    /** The request's other headers, lowercased and bounded, for providers that sign in a header
+     * (Stripe: `stripe-signature`). Never authority by themselves. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+
+export declare const iapNotificationNamespacesTable: Table<"_voltro_eco_iap_notice_namespaces", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly configurationDigest: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>;
+
+/** Authenticated delivery -> encrypted SQL custody -> fresh lookup -> actual financial group -> SQL completion fence. */
+export declare const iapNotificationProcessor: (input: IapNotificationProcessorOptions) => IapNotificationProcessorService;
+
+export declare interface IapNotificationProcessorOptions {
+    readonly deployment: IapNotificationTargetOptions;
+    readonly notifications: IapNotificationService;
+    readonly current: IapCurrentStateService;
+    readonly custody: IapNotificationCustodyService;
+    readonly refunds: IapRefundService;
+    readonly orders: Pick<IapSqlService, 'prepareNotification'>;
+    /** After a notice changed a purchase (see `IapNotificationsPluginOptions.onChange`). */
+    readonly changed?: ((change: IapPurchaseChange) => Effect.Effect<void, unknown>) | undefined;
+}
+
+export declare class IapNotificationProcessorPort extends IapNotificationProcessorPort_base {
+}
+
+declare const IapNotificationProcessorPort_base: Context.ServiceClass<IapNotificationProcessorPort, "@voltro/IapNotificationProcessorPort", IapNotificationProcessorService>;
+
+export declare interface IapNotificationProcessorService {
+    readonly initialize: () => Effect.Effect<void, EconomyError>;
+    /** `null`: an authenticated test notice (a store's TEST message, a provider event with no
+     * purchase in it) is acknowledged and not retained; no retry could ever process it. */
+    readonly ingest: (input: IapNotificationInput) => Effect.Effect<IapNotificationCustodyReceipt | null, EconomyError>;
+    readonly process: (id: string) => Effect.Effect<IapNotificationCustodyReceipt, EconomyError>;
+    readonly pending: () => Effect.Effect<readonly IapNotificationCustodyReceipt[], EconomyError>;
+    readonly prune: () => Effect.Effect<number, EconomyError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, EconomyError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, EconomyError>;
+}
+
+/** Normal discovered schedule descriptor; registration/cadence belong to the app. No timer or background runtime here. */
+export declare const iapNotificationSchedule: (input: IapNotificationScheduleOptions) => BrandedScheduleDefinition;
+
+export declare interface IapNotificationScheduleOptions extends IapNotificationWorkOptions {
+    readonly name: string;
+    readonly cron: string;
+    readonly timezone?: string;
+}
+
+declare interface IapNotificationService {
+    readonly initialize: () => Effect.Effect<void, EconomyError>;
+    readonly verify: (input: IapNotificationInput) => Effect.Effect<VerifiedIapNotification, EconomyError>;
+}
+
+export declare interface IapNotificationsPluginOptions {
+    readonly version: string;
+    readonly pathPrefix?: string;
+    readonly maxBodyBytes?: number;
+    readonly bodyRetentionMs?: number | undefined;
+    readonly debtPolicy?: IapDebtPolicy | undefined;
+    readonly assets?: IapRefundAssetParticipant | undefined;
+    readonly assetsVersion?: string | undefined;
+    readonly maxNoticeRows?: number;
+    readonly maxRefundRows?: number;
+    readonly cipher?: IapNotificationCipherSource | undefined;
+    /** Complete replacement owns authentication/current state/financial authority, queue and privacy. */
+    readonly service?: IapNotificationsSystemService;
+    /** Complete notification replacements may expose their own three-method event queue. */
+    readonly refundEvents?: IapRefundEventsService;
+    /** Custom borrowed-transaction SQL read. Omit when the custom system exposes no own order disposition. */
+    readonly refundDisposition?: IapRefundDispositionSource | undefined;
+    /** Runs after a notice changed a purchase (a refund, a revocation), e.g. to end game time at once:
+     * `rooms.moderation.recheckAccess({ tenantId, subjectId: ownerId })`. Best effort: a failure is
+     * ignored and the notice stays processed. Not with a complete replacement `service`. */
+    readonly onChange?: ((change: IapPurchaseChange) => Effect.Effect<void, unknown>) | undefined;
+}
+
+export declare class IapNotificationsSystemPort extends IapNotificationsSystemPort_base {
+}
+
+declare const IapNotificationsSystemPort_base: Context.ServiceClass<IapNotificationsSystemPort, "@voltro/IapNotificationsSystemPort", IapNotificationsSystemService>;
+
+export declare interface IapNotificationsSystemService {
+    readonly initialize: () => Effect.Effect<void, EconomyError>;
+    readonly processor: (channel: EconomyChannel) => Effect.Effect<IapNotificationProcessorService, EconomyError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, EconomyError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, EconomyError>;
+}
+
+export declare const iapNotificationsTable: Table<"_voltro_eco_iap_notices", 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 ownerKey: ColumnBuilder<string, "text", boolean>;
+    readonly orderId: ColumnBuilder<string, "text", boolean>;
+    readonly identity: ColumnBuilder<string, "text", boolean>;
+    readonly fingerprint: ColumnBuilder<string, "text", boolean>;
+    readonly state: ColumnBuilder<"erased" | "expired" | "pending" | "processed", "text", boolean>;
+    /** Already sealed by the SAME registered row-bound framework FieldCipher, like the connection vault. Never automatic double encryption. */
+    readonly sealedBody: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly expiresAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+export declare const iapNotificationSubjectsTable: Table<"_voltro_eco_iap_notice_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 iapNotificationTables: readonly [ Table<"_voltro_eco_iap_notice_namespaces", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+    readonly configurationDigest: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly rowsCount: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>, Table<"_voltro_eco_iap_notice_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_notices", 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 ownerKey: ColumnBuilder<string, "text", boolean>;
+    readonly orderId: ColumnBuilder<string, "text", boolean>;
+    readonly identity: ColumnBuilder<string, "text", boolean>;
+    readonly fingerprint: ColumnBuilder<string, "text", boolean>;
+    readonly state: ColumnBuilder<"erased" | "expired" | "pending" | "processed", "text", boolean>;
+    /** Already sealed by the SAME registered row-bound framework FieldCipher, like the connection vault. Never automatic double encryption. */
+    readonly sealedBody: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly expiresAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>];
+
+declare interface IapNotificationTargetOptions {
+    readonly realMoney: boolean;
+    readonly channel: IapRefundChannel;
+    readonly applicationId: string;
+    readonly environment: IapEnvironment;
+}
+
+export declare interface IapNotificationWorkOptions {
+    readonly processor: IapNotificationProcessorService;
+    readonly maxNotices?: number;
+}
+
+export declare interface IapNotificationWorkResult {
+    readonly prunedBodies: number;
+    readonly scannedRows: number;
+    readonly processedNotices: number;
+}
+
+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';
+
+/** A store or provider notice changed a purchase: a refund, a revocation. `ownerId` is the player. */
+export declare interface IapPurchaseChange {
+    readonly tenantId: string;
+    readonly ownerId: string;
+    readonly orderId: string;
+    readonly offerId: string;
+    readonly offerVersion: string;
+    readonly state: IapRefundReceipt['state'];
+}
+
+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;
+}
+
+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. */
+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';
+
+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>;
+}
+
+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;
+}
+
+declare type IapRefundEventPayload = typeof IapRefundEventPayloadSchema.Type;
+
+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;
+}>;
+
+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>;
+}
+
+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;
+}
+
+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>;
+}
+
+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';
+}
+
+/** Discovery may capture the installed facade before activation; resolution occurs only on a firing. */
+export declare const installedIapNotificationSchedule: (input: IapInstalledNotificationScheduleOptions) => BrandedScheduleDefinition;
+
+/** Actual pending SQL event authority. Copies and serialized payloads cannot authorize delivery acknowledgement. */
+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;
+}
+
+/** Explicit bounded SQL queue work. Earlier successful notices survive a later firing failure; retry reads SQL again. */
+export declare const runIapNotificationWork: (input: IapNotificationWorkOptions) => Effect.Effect<IapNotificationWorkResult, EconomyError>;
+
+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;
+
+export { }

package/dist/iapNotifications.js

@@ -0,0 +1,6 @@
+import { iapNotificationNamespacesTable as e, iapNotificationSubjectsTable as t, iapNotificationTables as n, iapNotificationsTable as r } from "./iapNotificationTables.entity.js";
+import { IapNotificationCustodyPort as i, captureIapNotificationCustodyService as a, dataStoreIapNotificationCustody as o } from "./iapNotificationStore.server.js";
+import { IapNotificationProcessorPort as s, captureIapNotificationProcessorService as c, iapNotificationHttpRoute as l, iapNotificationProcessor as u } from "./iapNotificationProcessor.server.js";
+import { IapNotificationsSystemPort as d, captureIapNotificationsSystemService as f } from "./iapNotificationsBinding.server.js";
+import { iapNotificationSchedule as p, installedIapNotificationSchedule as m, runIapNotificationWork as h } from "./iapNotificationSchedule.server.js";
+export { i as IapNotificationCustodyPort, s as IapNotificationProcessorPort, d as IapNotificationsSystemPort, a as captureIapNotificationCustodyService, c as captureIapNotificationProcessorService, f as captureIapNotificationsSystemService, o as dataStoreIapNotificationCustody, l as iapNotificationHttpRoute, e as iapNotificationNamespacesTable, u as iapNotificationProcessor, p as iapNotificationSchedule, t as iapNotificationSubjectsTable, n as iapNotificationTables, r as iapNotificationsTable, m as installedIapNotificationSchedule, h as runIapNotificationWork };