@plasius/economy 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,558 @@
+/** Number of indivisible subunits in one public Token. */
+declare const TOKEN_SUBUNITS_PER_TOKEN = 1000n;
+/** PostgreSQL-compatible signed bigint bounds. */
+declare const TOKEN_SUBUNITS_MIN: bigint;
+declare const TOKEN_SUBUNITS_MAX: bigint;
+declare const tokenSubunitStringBrand: unique symbol;
+/** Canonical base-10 representation used at JSON and persistence boundaries. */
+type TokenSubunitString = string & {
+    readonly [tokenSubunitStringBrand]: "TokenSubunitString";
+};
+/** Parses a canonical base-10 TokenSubunit string without floating point. */
+declare function parseTokenSubunits(value: string): bigint;
+/** Serializes a signed 64-bit TokenSubunit amount to canonical base-10. */
+declare function serializeTokenSubunits(amount: bigint): TokenSubunitString;
+/** Converts an exact whole-Token integer into TokenSubunits. */
+declare function wholeTokensToSubunits(tokens: bigint): bigint;
+/** Returns true when a subunit amount represents an exact whole Token. */
+declare function isWholeTokenAmount(amount: bigint): boolean;
+/** Converts TokenSubunits to whole Tokens, rejecting fractional progress. */
+declare function subunitsToWholeTokens(amount: bigint): bigint;
+/** Sums amount strings with signed 64-bit overflow protection. */
+declare function sumTokenSubunits(values: readonly string[]): bigint;
+
+declare const ECONOMY_CONTRACT_VERSION: "1";
+type EconomyContractVersion = typeof ECONOMY_CONTRACT_VERSION;
+type AccountId = string;
+type AllocationId = string;
+type HouseholdId = string;
+type LotId = string;
+type PostingId = string;
+type ProviderEventId = string;
+type TransactionId = string;
+type WalletId = string;
+type IsoTimestamp = string;
+/** Validates opaque pseudonymous domain identifiers. */
+declare function assertEconomyIdentifier(value: string, label?: string): void;
+/** Parses a bounded ISO timestamp and returns milliseconds since epoch. */
+declare function parseIsoTimestamp(value: IsoTimestamp): number;
+/** Returns a new record with keys sorted for canonical serialization. */
+declare function sortStringRecord(value: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+
+type ActivityType = "purchase" | "subscription" | "rewarded-ad" | "offerwall" | "allocation" | "boost" | "reclaim" | "spend" | "hold" | "refund" | "chargeback" | "adjustment" | "reversal" | "event" | "competition";
+type ActivityStatus = "pending" | "held" | "settled" | "reversed" | "failed";
+/** One signed side of an immutable double-entry transaction. */
+interface LedgerPostingV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly postingId: PostingId;
+    readonly transactionId: TransactionId;
+    readonly accountId: AccountId;
+    readonly walletId?: WalletId;
+    readonly lotId?: LotId;
+    readonly amount: TokenSubunitString;
+}
+/** Immutable transaction envelope. Posting amounts must sum to exactly zero. */
+interface LedgerTransactionV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly transactionId: TransactionId;
+    readonly activityType: ActivityType;
+    readonly status: ActivityStatus;
+    readonly idempotencyKey: string;
+    readonly providerEventId?: ProviderEventId;
+    readonly reversesTransactionId?: TransactionId;
+    readonly effectiveAt: IsoTimestamp;
+    readonly recordedAt: IsoTimestamp;
+    readonly previousCanonicalHash?: string;
+    readonly canonicalHash?: string;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly postings: readonly LedgerPostingV1[];
+}
+/** Privacy-safe, display-oriented journal entry returned by an API adapter. */
+interface ActivityEntryV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly transactionId: TransactionId;
+    readonly activityType: ActivityType;
+    readonly status: ActivityStatus;
+    readonly occurredAt: IsoTimestamp;
+    readonly amount: TokenSubunitString;
+    readonly beneficiaryAccountId?: AccountId;
+    readonly maskedReference?: string;
+    readonly sourceLabel: string;
+}
+/** Validates one privacy-safe activity row returned by an HTTP adapter. */
+declare function assertActivityEntry(entry: ActivityEntryV1): void;
+/** Proves the structural and arithmetic invariants of one transaction. */
+declare function assertBalancedTransaction(transaction: LedgerTransactionV1): void;
+/**
+ * Produces deterministic UTF-8 JSON for an approved SHA-256/HSM adapter.
+ * Hashing itself deliberately remains outside this provider-neutral package.
+ */
+declare function canonicalTransactionPayload(transaction: LedgerTransactionV1): string;
+interface ReversalInputV1 {
+    readonly transactionId: TransactionId;
+    readonly postingIds: readonly PostingId[];
+    readonly idempotencyKey: string;
+    readonly effectiveAt: IsoTimestamp;
+    readonly recordedAt: IsoTimestamp;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly previousCanonicalHash?: string;
+}
+/** Creates an immutable compensating transaction; it never edits the original. */
+declare function createReversalTransaction(original: LedgerTransactionV1, input: ReversalInputV1): LedgerTransactionV1;
+/** Rejects a second effective reversal for the same original transaction. */
+declare function assertReversalAvailable(originalTransactionId: TransactionId, existingTransactions: readonly LedgerTransactionV1[]): void;
+
+interface TokenPackV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly packId: string;
+    readonly catalogVersion: string;
+    readonly currency: "GBP";
+    readonly priceMinorUnits: string;
+    readonly grantAmount: TokenSubunitString;
+    readonly active: boolean;
+}
+/** Product-copy reference only; it is not a redemption or exchange promise. */
+interface TokenReferenceRateV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly rateVersion: string;
+    readonly currency: "GBP";
+    readonly referenceMinorUnitsPerToken: string;
+    readonly tokenSubunitsPerToken: string;
+    readonly cashRedemptionAllowed: false;
+}
+declare const BASELINE_GBP_REFERENCE_RATE: TokenReferenceRateV1;
+declare const BASELINE_GBP_CATALOG_VERSION: "gbp-v1";
+/** Initial flat-price public catalog. Changes require a new catalog version. */
+declare const BASELINE_GBP_TOKEN_PACKS: readonly TokenPackV1[];
+interface PurchaseLimitPolicyV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly maxOrderPriceMinorUnits: string;
+    readonly rollingPayerPriceMinorUnits: string;
+    readonly rollingHouseholdPriceMinorUnits: string;
+    readonly rollingDays: number;
+}
+/** Default server limits; household controls may only lower these values. */
+declare const BASELINE_PURCHASE_LIMIT_POLICY: PurchaseLimitPolicyV1;
+type PurchaseIntentStatus = "created" | "checkout-created" | "paid-unreconciled" | "credited" | "expired" | "cancelled" | "disputed";
+/** Short-lived server authority binding checkout facts to a payer/household. */
+interface PurchaseIntentV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly intentId: string;
+    readonly payerAccountId: AccountId;
+    readonly receivingHouseholdId: HouseholdId;
+    readonly receivingWalletId: WalletId;
+    readonly packId: string;
+    readonly catalogVersion: string;
+    readonly expectedCurrency: "GBP";
+    readonly expectedPriceMinorUnits: string;
+    readonly grantAmount: TokenSubunitString;
+    readonly status: PurchaseIntentStatus;
+    readonly createdAt: IsoTimestamp;
+    readonly expiresAt: IsoTimestamp;
+    readonly providerCheckoutReferenceHash?: string;
+}
+interface RewardRateV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly rateVersion: string;
+    readonly provider: "ayet" | "bitlabs";
+    /** TokenSubunits granted per denominator of authoritative GBP minor units. */
+    readonly tokenSubunitsNumerator: string;
+    readonly gbpMinorUnitsDenominator: string;
+    readonly effectiveFrom: IsoTimestamp;
+    readonly effectiveUntil?: IsoTimestamp;
+}
+interface FxSnapshotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly snapshotId: string;
+    readonly sourceCurrency: string;
+    readonly quoteCurrency: "GBP";
+    /** Exact rational conversion to GBP minor units. */
+    readonly gbpMinorUnitsNumerator: string;
+    readonly sourceMinorUnitsDenominator: string;
+    readonly capturedAt: IsoTimestamp;
+}
+type RewardConversionStatus = "pending" | "completed" | "reconciled";
+type BitLabsConversionState = "PENDING" | "COMPLETED" | "RECONCILED";
+interface RewardActivityTransitionV1 {
+    readonly conversionStatus: RewardConversionStatus;
+    readonly activityType: ActivityType;
+    readonly activityStatus: ActivityStatus;
+}
+interface RewardConversionV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly provider: "ayet" | "bitlabs";
+    readonly providerEventId: ProviderEventId;
+    readonly beneficiaryAccountId: AccountId;
+    readonly walletId: WalletId;
+    readonly status: RewardConversionStatus;
+    readonly providerPayoutMinorUnits: string;
+    readonly providerCurrency: string;
+    readonly gbpMinorUnits: string;
+    readonly tokenSubunits: TokenSubunitString;
+    readonly rateVersion: string;
+    readonly fxSnapshotId: string;
+    readonly occurredAt: IsoTimestamp;
+}
+/** Validates a minimized, signed-provider conversion record before journaling. */
+declare function assertRewardConversion(conversion: RewardConversionV1): void;
+/** Validates a paid pack; pack grants are whole Tokens in the baseline. */
+declare function assertTokenPack(pack: TokenPackV1): void;
+/** Validates nominal reference metadata without creating redemption rights. */
+declare function assertTokenReferenceRate(rate: TokenReferenceRateV1): void;
+/** Proves that every pack in one catalog uses the same flat nominal ratio. */
+declare function assertFlatTokenCatalog(packs: readonly TokenPackV1[], referenceRate: TokenReferenceRateV1): void;
+/** Validates server-side order and rolling acquisition ceilings. */
+declare function assertPurchaseLimitPolicy(policy: PurchaseLimitPolicyV1): void;
+/** Validates the immutable server-side facts bound into a purchase intent. */
+declare function assertPurchaseIntentBinding(intent: PurchaseIntentV1, pack: TokenPackV1): void;
+/** Rejects stale, inactive, or already-consumed intents before checkout creation. */
+declare function assertOpenPurchaseIntent(intent: PurchaseIntentV1, pack: TokenPackV1, checkedAt: IsoTimestamp): void;
+declare function assertRewardRate(rate: RewardRateV1): void;
+declare function assertFxSnapshot(fx: FxSnapshotV1): void;
+/** Converts provider payout using exact rational FX and rate snapshots. */
+declare function convertRewardPayout(providerPayoutMinorUnits: string, rate: RewardRateV1, fx: FxSnapshotV1): {
+    readonly gbpMinorUnits: string;
+    readonly tokenSubunits: TokenSubunitString;
+};
+/** Maps BitLabs' signed callback state into an immutable journal transition. */
+declare function mapBitLabsConversionState(state: string): RewardActivityTransitionV1;
+
+type TokenSource = "shopify" | "ayet" | "bitlabs" | "subscription" | "event" | "competition" | "adjustment";
+type LotTransferPolicy = "household-allocatable" | "same-user-only" | "non-transferable";
+type LotRefundState = "none" | "partial" | "refunded" | "disputed" | "chargeback-lost";
+interface SourceLotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly lotId: LotId;
+    readonly walletId: WalletId;
+    readonly beneficiaryAccountId: AccountId;
+    readonly householdId?: HouseholdId;
+    readonly payerAccountId?: AccountId;
+    readonly source: TokenSource;
+    readonly providerEventId?: ProviderEventId;
+    readonly rateVersion: string;
+    readonly settlementEvidenceHash: string;
+    readonly transferPolicy: LotTransferPolicy;
+    readonly refundState: LotRefundState;
+    readonly originalAmount: TokenSubunitString;
+    readonly remainingAmount: TokenSubunitString;
+    readonly heldAmount: TokenSubunitString;
+    readonly reversedAmount: TokenSubunitString;
+    readonly settledAt: IsoTimestamp;
+    readonly creditedAt: IsoTimestamp;
+    readonly cohortKey?: string;
+}
+type LotUseOperation = "allocate" | "spend" | "reclaim" | "refund";
+interface LotUseContextV1 {
+    readonly operation: LotUseOperation;
+    readonly beneficiaryAccountId: AccountId;
+    readonly householdId?: HouseholdId;
+}
+interface SourceLotSliceV1 {
+    readonly lotId: LotId;
+    readonly amount: TokenSubunitString;
+}
+/** Validates source-lot arithmetic, evidence, and immutable provenance fields. */
+declare function assertSourceLot(lot: SourceLotV1): void;
+/** Returns unheld, unconsumed TokenSubunits in a source lot. */
+declare function availableSourceLotAmount(lot: SourceLotV1): bigint;
+/** Evaluates provider/source restrictions without trusting a browser claim. */
+declare function canUseSourceLot(lot: SourceLotV1, context: LotUseContextV1): boolean;
+/**
+ * Selects eligible lots deterministically in credited-time/lot-id order.
+ * The returned slices are a proposal; persistence must consume them atomically.
+ */
+declare function selectSourceLots(lots: readonly SourceLotV1[], requestedAmount: TokenSubunitString, context: LotUseContextV1): readonly SourceLotSliceV1[];
+
+type AllocationStatus = "active" | "closed";
+type PeriodicLimitWindow = "daily" | "weekly" | "monthly";
+interface GameplayLimitsV1 {
+    readonly perTransaction: TokenSubunitString;
+    readonly periodic: TokenSubunitString;
+    readonly periodicWindow: PeriodicLimitWindow;
+}
+/** Guardian-funded, child-visible reservation. This is not a gameplay ledger. */
+interface GameplayAllocationV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly allocationId: AllocationId;
+    readonly householdId: HouseholdId;
+    readonly hostWalletId: WalletId;
+    readonly childWalletId: WalletId;
+    readonly childAccountId: AccountId;
+    readonly status: AllocationStatus;
+    readonly reservedAmount: TokenSubunitString;
+    readonly remainingAmount: TokenSubunitString;
+    readonly reclaimedAmount: TokenSubunitString;
+    readonly fundingSlices: readonly SourceLotSliceV1[];
+    readonly reclaimedSlices: readonly SourceLotSliceV1[];
+    readonly limits: GameplayLimitsV1;
+    readonly version: number;
+    readonly createdAt: IsoTimestamp;
+    readonly updatedAt: IsoTimestamp;
+}
+/** Validates allocation arithmetic and whole-Token reservation policy. */
+declare function assertGameplayAllocation(allocation: GameplayAllocationV1): void;
+interface CreateGameplayAllocationInputV1 {
+    readonly allocationId: AllocationId;
+    readonly householdId: HouseholdId;
+    readonly hostWalletId: WalletId;
+    readonly childWalletId: WalletId;
+    readonly childAccountId: AccountId;
+    readonly amount: TokenSubunitString;
+    readonly fundingSlices: readonly SourceLotSliceV1[];
+    readonly limits: GameplayLimitsV1;
+    readonly occurredAt: IsoTimestamp;
+}
+/** Creates a new whole-Token reservation from already-selected source lots. */
+declare function createGameplayAllocation(input: CreateGameplayAllocationInputV1): GameplayAllocationV1;
+interface BoostGameplayAllocationInputV1 {
+    readonly amount: TokenSubunitString;
+    readonly fundingSlices: readonly SourceLotSliceV1[];
+    readonly expectedVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+/** Returns the next immutable allocation state after a whole-Token boost. */
+declare function boostGameplayAllocation(allocation: GameplayAllocationV1, input: BoostGameplayAllocationInputV1): GameplayAllocationV1;
+interface ReclaimGameplayAllocationInputV1 {
+    readonly amount: TokenSubunitString;
+    readonly sourceSlices: readonly SourceLotSliceV1[];
+    readonly expectedVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+/** Reclaims unused whole Tokens without changing spent history. */
+declare function reclaimGameplayAllocation(allocation: GameplayAllocationV1, input: ReclaimGameplayAllocationInputV1): GameplayAllocationV1;
+
+declare const PRE_UTILITY_BACKER_COHORT: "pre_utility_backer_v1";
+interface EarlyBackerWindowV1 {
+    readonly publicTokensLaunchAt: IsoTimestamp;
+    readonly firstPublicSpendLiveAt?: IsoTimestamp;
+}
+/** Paid-lot facts required to recalculate retained early-backer basis. */
+interface PaidLotRetentionV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly lotId: LotId;
+    readonly payerAccountId: AccountId;
+    readonly receivingHouseholdId: HouseholdId;
+    readonly purchaseId: string;
+    readonly catalogVersion: string;
+    readonly purchasedAt: IsoTimestamp;
+    readonly settledAt: IsoTimestamp;
+    readonly creditedAt: IsoTimestamp;
+    readonly retainedAmount: TokenSubunitString;
+}
+interface EarlyBackerEvaluationV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly cohortKey: typeof PRE_UTILITY_BACKER_COHORT;
+    readonly status: "not-qualified" | "provisional";
+    readonly payerAccountId: AccountId;
+    readonly receivingHouseholdId: HouseholdId;
+    readonly netRetainedAmount: TokenSubunitString;
+    readonly contributingLotIds: readonly LotId[];
+    readonly evaluatedAt: IsoTimestamp;
+}
+/**
+ * Recalculates provisional cohort basis from retained paid lots. It promises no
+ * future reward and deliberately has no permanent entitled state.
+ */
+declare function evaluateEarlyBacker(payerAccountId: AccountId, receivingHouseholdId: HouseholdId, paidLots: readonly PaidLotRetentionV1[], window: EarlyBackerWindowV1, evaluatedAt: IsoTimestamp): EarlyBackerEvaluationV1;
+
+/** Stable machine-readable failures exposed by the economy domain. */
+type EconomyErrorCode = "INVALID_AMOUNT" | "AMOUNT_OUT_OF_RANGE" | "AMOUNT_NOT_WHOLE_TOKEN" | "INVALID_CONTRACT" | "UNBALANCED_TRANSACTION" | "DUPLICATE_IDENTIFIER" | "DUPLICATE_TRANSACTION" | "INSUFFICIENT_BALANCE" | "INSUFFICIENT_ELIGIBLE_LOTS" | "SOURCE_LOT_RESTRICTED" | "REVERSAL_ALREADY_EXISTS" | "NEGATIVE_PROJECTION" | "INVALID_TIME_WINDOW";
+interface EconomyErrorEnvelopeV1 {
+    readonly schemaVersion: "1";
+    readonly error: {
+        readonly code: EconomyErrorCode;
+        readonly message: string;
+        readonly requestId?: string;
+    };
+}
+/**
+ * Domain error with a stable code and deliberately non-sensitive message.
+ * Provider evidence, identities, and payment details must not be included.
+ */
+declare class EconomyError extends Error {
+    readonly code: EconomyErrorCode;
+    constructor(code: EconomyErrorCode, message: string);
+}
+/** Throws a stable economy error when a domain assertion fails. */
+declare function economyAssert(condition: unknown, code: EconomyErrorCode, message: string): asserts condition;
+/** Creates a bounded, non-sensitive error contract for an HTTP adapter. */
+declare function toEconomyErrorEnvelope(error: EconomyError, requestId?: string): EconomyErrorEnvelopeV1;
+
+type AdjustmentStatus = "draft" | "pending-approval" | "approved" | "rejected" | "executed" | "expired";
+/** Dual-control request; the resulting change is always a ledger transaction. */
+interface AdjustmentRequestV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly adjustmentId: string;
+    readonly walletId: WalletId;
+    readonly amount: TokenSubunitString;
+    readonly reason: string;
+    readonly ticketReference: string;
+    readonly status: AdjustmentStatus;
+    readonly initiatedByAccountId: AccountId;
+    readonly initiatedAt: IsoTimestamp;
+    readonly approvedByAccountId?: AccountId;
+    readonly approvedAt?: IsoTimestamp;
+    readonly resultingTransactionId?: TransactionId;
+}
+/** Proves that production adjustment approval was performed by another actor. */
+declare function assertDistinctAdjustmentApproval(request: AdjustmentRequestV1): void;
+
+type BalanceProjection = Readonly<Record<AccountId, TokenSubunitString>>;
+interface BalanceProjectionSnapshotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly balances: BalanceProjection;
+    readonly lastTransactionId?: TransactionId;
+    readonly rebuiltAt: IsoTimestamp;
+}
+/** Applies one balanced transaction without mutating the existing projection. */
+declare function applyTransactionToProjection(current: BalanceProjection, transaction: LedgerTransactionV1): BalanceProjection;
+/**
+ * Rebuilds balances deterministically and rejects duplicate economic envelopes.
+ */
+declare function rebuildBalanceProjection(transactions: readonly LedgerTransactionV1[]): BalanceProjection;
+/** Enforces non-negative balances only for spendable/reservable accounts. */
+declare function assertNonNegativeAccounts(projection: BalanceProjection, protectedAccountIds: readonly AccountId[]): void;
+/** Creates a versioned snapshot after a deterministic rebuild. */
+declare function createProjectionSnapshot(transactions: readonly LedgerTransactionV1[], rebuiltAt: IsoTimestamp): BalanceProjectionSnapshotV1;
+
+type WalletKind = "household-treasury" | "personal" | "gameplay-allocation" | "hold" | "purchase-clearing" | "provider-clearing" | "system";
+type WalletStatus = "active" | "restricted" | "closed";
+type WalletOwnerType = "account" | "household" | "system";
+/** Versioned authoritative wallet descriptor. */
+interface WalletV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly walletId: WalletId;
+    readonly accountId: AccountId;
+    readonly kind: WalletKind;
+    readonly ownerType: WalletOwnerType;
+    readonly ownerId: AccountId | HouseholdId | "system";
+    readonly householdId?: HouseholdId;
+    readonly status: WalletStatus;
+    readonly version: number;
+    readonly createdAt: IsoTimestamp;
+    readonly closedAt?: IsoTimestamp;
+}
+/** Server-computed wallet totals. Clients must never derive authority from it. */
+interface WalletBalanceSummaryV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly walletId: WalletId;
+    readonly available: TokenSubunitString;
+    readonly reserved: TokenSubunitString;
+    readonly held: TokenSubunitString;
+    readonly rewardProgress: TokenSubunitString;
+    readonly version: number;
+    readonly asOf: IsoTimestamp;
+}
+/** Lifetime aggregates used by the Token profile. */
+interface WalletLifetimeTotalsV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly bought: TokenSubunitString;
+    readonly earned: TokenSubunitString;
+    readonly allocated: TokenSubunitString;
+    readonly reclaimed: TokenSubunitString;
+    readonly spent: TokenSubunitString;
+    readonly reversed: TokenSubunitString;
+}
+/** Validates wallet ownership, lifecycle, and optimistic-version facts. */
+declare function assertWallet(wallet: WalletV1): void;
+/** Validates non-negative server-computed wallet balance categories. */
+declare function assertWalletBalanceSummary(summary: WalletBalanceSummaryV1): void;
+/** Validates non-negative lifetime aggregates exposed by the profile API. */
+declare function assertWalletLifetimeTotals(totals: WalletLifetimeTotalsV1): void;
+
+type EconomyCommandType = "credit-purchase" | "credit-reward" | "allocate" | "boost" | "reclaim" | "hold" | "refund" | "chargeback" | "adjust";
+interface EconomyCommandEnvelopeV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly commandId: string;
+    readonly commandType: EconomyCommandType;
+    readonly idempotencyKey: string;
+    readonly actorAccountId: AccountId;
+    readonly subjectAccountId: AccountId;
+    readonly relationshipId?: string;
+    readonly authorizationVersion?: number;
+    readonly payloadHash: string;
+    readonly acceptedAt: IsoTimestamp;
+    readonly acceptedRegion: string;
+    readonly writerFencingToken: string;
+}
+interface EconomyOutboxEventV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly eventId: string;
+    readonly transactionId: TransactionId;
+    readonly eventType: string;
+    readonly payloadHash: string;
+    readonly occurredAt: IsoTimestamp;
+}
+interface PersistedIdempotencyResultV1 {
+    readonly transactionId: TransactionId;
+    readonly responseHash: string;
+    readonly recordedAt: IsoTimestamp;
+}
+/** Operations available only inside one serializable database transaction. */
+interface EconomyUnitOfWork {
+    getWalletForUpdate(walletId: WalletId): Promise<WalletV1 | null>;
+    listSpendableLotsForUpdate(walletId: WalletId): Promise<readonly SourceLotV1[]>;
+    findLotForUpdate(lotId: LotId): Promise<SourceLotV1 | null>;
+    findIdempotencyResult(idempotencyKey: string): Promise<PersistedIdempotencyResultV1 | null>;
+    appendTransaction(transaction: LedgerTransactionV1): Promise<void>;
+    appendSourceLot(lot: SourceLotV1): Promise<void>;
+    updateSourceLotProjection(lotId: LotId, remainingAmount: TokenSubunitString, heldAmount: TokenSubunitString, reversedAmount: TokenSubunitString): Promise<void>;
+    saveBalanceProjection(projection: BalanceProjection, transactionId: TransactionId): Promise<void>;
+    saveIdempotencyResult(idempotencyKey: string, result: PersistedIdempotencyResultV1): Promise<void>;
+    appendOutboxEvent(event: EconomyOutboxEventV1): Promise<void>;
+}
+/** Adapter boundary for serializable, ACID economy mutations. */
+interface EconomyPersistencePort {
+    runSerializable<T>(operation: (unitOfWork: EconomyUnitOfWork) => Promise<T>): Promise<T>;
+    getWallet(walletId: WalletId): Promise<WalletV1 | null>;
+    getBalanceProjection(walletId: WalletId): Promise<BalanceProjectionSnapshotV1 | null>;
+    getTransaction(transactionId: TransactionId): Promise<LedgerTransactionV1 | null>;
+    rebuildProjection(): Promise<BalanceProjection>;
+}
+interface EconomyClockPort {
+    now(): IsoTimestamp;
+}
+interface EconomyIdPort {
+    nextId(namespace: string): string;
+}
+
+type RecurrenceInterval = "daily" | "weekly" | "monthly";
+/** Provider-neutral subscription contract. Site policy controls enablement. */
+interface TokenSubscriptionPlanV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly planId: string;
+    readonly catalogVersion: string;
+    readonly interval: RecurrenceInterval;
+    readonly priceMinorUnits: string;
+    readonly currency: "GBP";
+    readonly grantAmount: TokenSubunitString;
+    readonly enabled: boolean;
+    readonly effectiveFrom: IsoTimestamp;
+}
+/** Future convenience plan contract; disabled until public spend is live. */
+declare const BASELINE_MONTHLY_SUBSCRIPTION_PLAN: TokenSubscriptionPlanV1;
+/** Validates future provider-neutral recurrence without enabling it. */
+declare function assertTokenSubscriptionPlan(plan: TokenSubscriptionPlanV1): void;
+
+type SpendRequestPurpose = "gameplay-conversion" | "non-gameplay";
+type SpendRequestStatus = "requested" | "approved" | "rejected" | "expired" | "executed" | "cancelled";
+/** Future child request; baseline adapters must reject creation while disabled. */
+interface SpendRequestV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly requestId: string;
+    readonly childAccountId: AccountId;
+    readonly allocationId: AllocationId;
+    readonly purpose: SpendRequestPurpose;
+    readonly amount: TokenSubunitString;
+    readonly status: SpendRequestStatus;
+    readonly requestedAt: IsoTimestamp;
+    readonly expiresAt: IsoTimestamp;
+    readonly decidedByAccountId?: AccountId;
+    readonly decidedAt?: IsoTimestamp;
+    readonly approvalNonceHash?: string;
+    readonly resultingTransactionId?: TransactionId;
+}
+/** Validates future child requests while creation remains policy-disabled. */
+declare function assertSpendRequest(request: SpendRequestV1): void;
+
+export { type AccountId, type ActivityEntryV1, type ActivityStatus, type ActivityType, type AdjustmentRequestV1, type AdjustmentStatus, type AllocationId, type AllocationStatus, BASELINE_GBP_CATALOG_VERSION, BASELINE_GBP_REFERENCE_RATE, BASELINE_GBP_TOKEN_PACKS, BASELINE_MONTHLY_SUBSCRIPTION_PLAN, BASELINE_PURCHASE_LIMIT_POLICY, type BalanceProjection, type BalanceProjectionSnapshotV1, type BitLabsConversionState, type BoostGameplayAllocationInputV1, type CreateGameplayAllocationInputV1, ECONOMY_CONTRACT_VERSION, type EarlyBackerEvaluationV1, type EarlyBackerWindowV1, type EconomyClockPort, type EconomyCommandEnvelopeV1, type EconomyCommandType, type EconomyContractVersion, EconomyError, type EconomyErrorCode, type EconomyErrorEnvelopeV1, type EconomyIdPort, type EconomyOutboxEventV1, type EconomyPersistencePort, type EconomyUnitOfWork, type FxSnapshotV1, type GameplayAllocationV1, type GameplayLimitsV1, type HouseholdId, type IsoTimestamp, type LedgerPostingV1, type LedgerTransactionV1, type LotId, type LotRefundState, type LotTransferPolicy, type LotUseContextV1, type LotUseOperation, PRE_UTILITY_BACKER_COHORT, type PaidLotRetentionV1, type PeriodicLimitWindow, type PersistedIdempotencyResultV1, type PostingId, type ProviderEventId, type PurchaseIntentStatus, type PurchaseIntentV1, type PurchaseLimitPolicyV1, type ReclaimGameplayAllocationInputV1, type RecurrenceInterval, type ReversalInputV1, type RewardActivityTransitionV1, type RewardConversionStatus, type RewardConversionV1, type RewardRateV1, type SourceLotSliceV1, type SourceLotV1, type SpendRequestPurpose, type SpendRequestStatus, type SpendRequestV1, TOKEN_SUBUNITS_MAX, TOKEN_SUBUNITS_MIN, TOKEN_SUBUNITS_PER_TOKEN, type TokenPackV1, type TokenReferenceRateV1, type TokenSource, type TokenSubscriptionPlanV1, type TokenSubunitString, type TransactionId, type WalletBalanceSummaryV1, type WalletId, type WalletKind, type WalletLifetimeTotalsV1, type WalletOwnerType, type WalletStatus, type WalletV1, applyTransactionToProjection, assertActivityEntry, assertBalancedTransaction, assertDistinctAdjustmentApproval, assertEconomyIdentifier, assertFlatTokenCatalog, assertFxSnapshot, assertGameplayAllocation, assertNonNegativeAccounts, assertOpenPurchaseIntent, assertPurchaseIntentBinding, assertPurchaseLimitPolicy, assertReversalAvailable, assertRewardConversion, assertRewardRate, assertSourceLot, assertSpendRequest, assertTokenPack, assertTokenReferenceRate, assertTokenSubscriptionPlan, assertWallet, assertWalletBalanceSummary, assertWalletLifetimeTotals, availableSourceLotAmount, boostGameplayAllocation, canUseSourceLot, canonicalTransactionPayload, convertRewardPayout, createGameplayAllocation, createProjectionSnapshot, createReversalTransaction, economyAssert, evaluateEarlyBacker, isWholeTokenAmount, mapBitLabsConversionState, parseIsoTimestamp, parseTokenSubunits, rebuildBalanceProjection, reclaimGameplayAllocation, selectSourceLots, serializeTokenSubunits, sortStringRecord, subunitsToWholeTokens, sumTokenSubunits, toEconomyErrorEnvelope, wholeTokensToSubunits };