@plasius/economy 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -26,7 +26,12 @@ type EconomyContractVersion = typeof ECONOMY_CONTRACT_VERSION;
 type AccountId = string;
 type AllocationId = string;
 type HouseholdId = string;
+type LearningEntitlementId = string;
+type LearningModuleVersionId = string;
 type LotId = string;
+type ModuleAllowanceId = string;
+type ModuleSpendHoldId = string;
+type ModuleSpendQuoteId = string;
 type PostingId = string;
 type ProviderEventId = string;
 type TransactionId = string;
@@ -484,6 +489,204 @@ declare function assertJournalChainHead(head: JournalChainHeadV1): void;
  */
 declare function advanceJournalChainHead(head: JournalChainHeadV1, transaction: ChainedEconomicJournalTransactionV1): JournalChainHeadV1;
 
+declare const MODULE_ALLOWANCE_PURPOSE: "junior-coder-module-entitlement";
+type ModuleAllowanceStatusV1 = "active" | "closed";
+/** Guardian-funded value that can only purchase modules for one child. */
+interface ModuleAllowanceV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly purpose: typeof MODULE_ALLOWANCE_PURPOSE;
+    readonly allowanceId: ModuleAllowanceId;
+    readonly householdId: HouseholdId;
+    readonly hostWalletId: WalletId;
+    readonly allowanceWalletId: WalletId;
+    readonly childAccountId: AccountId;
+    readonly status: ModuleAllowanceStatusV1;
+    readonly allocatedAmount: TokenSubunitString;
+    readonly availableAmount: TokenSubunitString;
+    readonly heldAmount: TokenSubunitString;
+    readonly spentAmount: TokenSubunitString;
+    readonly reclaimedAmount: TokenSubunitString;
+    readonly fundingSlices: readonly SourceLotSliceV1[];
+    readonly reclaimedSlices: readonly SourceLotSliceV1[];
+    readonly version: number;
+    readonly createdAt: IsoTimestamp;
+    readonly updatedAt: IsoTimestamp;
+}
+interface CreateModuleAllowanceInputV1 {
+    readonly allowanceId: ModuleAllowanceId;
+    readonly householdId: HouseholdId;
+    readonly hostWalletId: WalletId;
+    readonly allowanceWalletId: WalletId;
+    readonly childAccountId: AccountId;
+    readonly amount: TokenSubunitString;
+    readonly fundingSlices: readonly SourceLotSliceV1[];
+    readonly occurredAt: IsoTimestamp;
+}
+interface FundModuleAllowanceInputV1 {
+    readonly amount: TokenSubunitString;
+    readonly fundingSlices: readonly SourceLotSliceV1[];
+    readonly expectedVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+interface ReclaimModuleAllowanceInputV1 {
+    readonly amount: TokenSubunitString;
+    readonly sourceSlices: readonly SourceLotSliceV1[];
+    readonly expectedVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+interface CloseModuleAllowanceInputV1 {
+    readonly expectedVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+/** Immutable Guardian-approved module price and requirements evidence. */
+interface ModuleSpendQuoteV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly quoteId: ModuleSpendQuoteId;
+    readonly allowanceId: ModuleAllowanceId;
+    readonly householdId: HouseholdId;
+    readonly guardianAccountId: AccountId;
+    readonly childAccountId: AccountId;
+    readonly moduleVersionId: LearningModuleVersionId;
+    readonly catalogVersion: string;
+    readonly amount: TokenSubunitString;
+    readonly requirementsManifestVersion: string;
+    readonly requirementsManifestHash: string;
+    readonly requirementsAcknowledgedAt: IsoTimestamp;
+    readonly issuedAt: IsoTimestamp;
+    readonly expiresAt: IsoTimestamp;
+}
+type CreateModuleSpendQuoteInputV1 = Omit<ModuleSpendQuoteV1, "schemaVersion">;
+type ModuleSpendHoldStatusV1 = "held" | "settled" | "released";
+/** Versioned projection for one quote-bound allowance hold. */
+interface ModuleSpendHoldV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly holdId: ModuleSpendHoldId;
+    readonly quoteId: ModuleSpendQuoteId;
+    readonly allowanceId: ModuleAllowanceId;
+    readonly householdId: HouseholdId;
+    readonly guardianAccountId: AccountId;
+    readonly childAccountId: AccountId;
+    readonly moduleVersionId: LearningModuleVersionId;
+    readonly amount: TokenSubunitString;
+    readonly requirementsManifestVersion: string;
+    readonly requirementsManifestHash: string;
+    readonly sourceSlices: readonly SourceLotSliceV1[];
+    readonly status: ModuleSpendHoldStatusV1;
+    readonly holdIdempotencyKey: string;
+    readonly settlementIdempotencyKey?: string;
+    readonly releaseIdempotencyKey?: string;
+    readonly entitlementId?: LearningEntitlementId;
+    readonly settlementTransactionId?: TransactionId;
+    readonly releaseTransactionId?: TransactionId;
+    readonly version: number;
+    readonly createdAt: IsoTimestamp;
+    readonly expiresAt: IsoTimestamp;
+    readonly updatedAt: IsoTimestamp;
+}
+interface CreateModuleSpendHoldInputV1 {
+    readonly holdId: ModuleSpendHoldId;
+    readonly idempotencyKey: string;
+    readonly sourceSlices: readonly SourceLotSliceV1[];
+    readonly expectedAllowanceVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+interface SettleModuleSpendHoldInputV1 {
+    readonly entitlementId: LearningEntitlementId;
+    readonly settlementTransactionId: TransactionId;
+    readonly idempotencyKey: string;
+    readonly expectedAllowanceVersion: number;
+    readonly expectedHoldVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+interface ReleaseModuleSpendHoldInputV1 {
+    readonly releaseTransactionId: TransactionId;
+    readonly idempotencyKey: string;
+    readonly expectedAllowanceVersion: number;
+    readonly expectedHoldVersion: number;
+    readonly occurredAt: IsoTimestamp;
+}
+interface ModuleSpendTransitionResultV1 {
+    readonly allowance: ModuleAllowanceV1;
+    readonly hold: ModuleSpendHoldV1;
+}
+/** Durable economic receipt for an activated learning entitlement. */
+interface ModulePurchaseReceiptV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly receiptId: string;
+    readonly quoteId: ModuleSpendQuoteId;
+    readonly holdId: ModuleSpendHoldId;
+    readonly allowanceId: ModuleAllowanceId;
+    readonly householdId: HouseholdId;
+    readonly guardianAccountId: AccountId;
+    readonly childAccountId: AccountId;
+    readonly moduleVersionId: LearningModuleVersionId;
+    readonly entitlementId: LearningEntitlementId;
+    readonly amount: TokenSubunitString;
+    readonly requirementsManifestVersion: string;
+    readonly requirementsManifestHash: string;
+    readonly settlementTransactionId: TransactionId;
+    readonly issuedAt: IsoTimestamp;
+}
+interface CreateModulePurchaseReceiptInputV1 {
+    readonly receiptId: string;
+    readonly issuedAt: IsoTimestamp;
+}
+type ModulePurchaseFinancialStateV1 = "missing" | "held" | "settled" | "released";
+type ModulePurchaseEntitlementStateV1 = "missing" | "pending" | "active" | "cancelled";
+/** Privacy-minimized observation used by an authoritative reconciler. */
+interface ModulePurchaseReconciliationObservationV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly quoteId: ModuleSpendQuoteId;
+    readonly holdId: ModuleSpendHoldId;
+    readonly childAccountId: AccountId;
+    readonly moduleVersionId: LearningModuleVersionId;
+    readonly financialState: ModulePurchaseFinancialStateV1;
+    readonly entitlementState: ModulePurchaseEntitlementStateV1;
+    readonly receiptPresent: boolean;
+    readonly observedAt: IsoTimestamp;
+}
+type ModulePurchaseReconciliationActionV1 = "none" | "resume-settlement" | "release-hold" | "activate-entitlement" | "issue-receipt" | "cancel-pending-entitlement" | "manual-review";
+interface ModulePurchaseReconciliationResultV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly action: ModulePurchaseReconciliationActionV1;
+    readonly blocking: boolean;
+    readonly consistent: boolean;
+    readonly reasonCode: string;
+}
+/** Validates exact arithmetic and source-lot provenance for an allowance. */
+declare function assertModuleAllowance(allowance: ModuleAllowanceV1): void;
+/** Creates a child-specific Module Allowance from locked source-lot slices. */
+declare function createModuleAllowance(input: CreateModuleAllowanceInputV1): ModuleAllowanceV1;
+/** Adds Guardian-selected source-lot value without replacing prior history. */
+declare function fundModuleAllowance(allowance: ModuleAllowanceV1, input: FundModuleAllowanceInputV1): ModuleAllowanceV1;
+/** Returns unused value to its source lots without changing spent history. */
+declare function reclaimModuleAllowance(allowance: ModuleAllowanceV1, input: ReclaimModuleAllowanceInputV1): ModuleAllowanceV1;
+/** Closes an empty allowance; funding later requires a new allowance. */
+declare function closeModuleAllowance(allowance: ModuleAllowanceV1, input: CloseModuleAllowanceInputV1): ModuleAllowanceV1;
+/** Validates immutable price, Guardian acknowledgement, and manifest evidence. */
+declare function assertModuleSpendQuote(quote: ModuleSpendQuoteV1): void;
+/** Creates immutable quote evidence from server-derived catalog facts. */
+declare function createModuleSpendQuote(input: CreateModuleSpendQuoteInputV1): ModuleSpendQuoteV1;
+/** Validates one quote-bound hold lifecycle projection. */
+declare function assertModuleSpendHold(hold: ModuleSpendHoldV1): void;
+/** Moves quoted value from available to held after all bindings are checked. */
+declare function createModuleSpendHold(allowance: ModuleAllowanceV1, quote: ModuleSpendQuoteV1, input: CreateModuleSpendHoldInputV1): ModuleSpendTransitionResultV1;
+/** Settles a hold only when the pending learning entitlement is identified. */
+declare function settleModuleSpendHold(allowance: ModuleAllowanceV1, hold: ModuleSpendHoldV1, input: SettleModuleSpendHoldInputV1): ModuleSpendTransitionResultV1;
+/** Releases failed or expired held value back to the same allowance. */
+declare function releaseModuleSpendHold(allowance: ModuleAllowanceV1, hold: ModuleSpendHoldV1, input: ReleaseModuleSpendHoldInputV1): ModuleSpendTransitionResultV1;
+/** Validates a durable receipt against settled economic evidence. */
+declare function assertModulePurchaseReceipt(receipt: ModulePurchaseReceiptV1): void;
+/** Creates a receipt only when quote and settled hold evidence match exactly. */
+declare function createModulePurchaseReceipt(quote: ModuleSpendQuoteV1, hold: ModuleSpendHoldV1, input: CreateModulePurchaseReceiptInputV1): ModulePurchaseReceiptV1;
+/** Validates privacy-minimized cross-service reconciliation evidence. */
+declare function assertModulePurchaseReconciliationObservation(observation: ModulePurchaseReconciliationObservationV1): void;
+/**
+ * Returns one forward-safe action. Callers must reload and lock authoritative
+ * state before carrying it out; `manual-review` never authorizes a mutation.
+ */
+declare function reconcileModulePurchase(observation: ModulePurchaseReconciliationObservationV1): ModulePurchaseReconciliationResultV1;
+
 type AdjustmentStatus = "draft" | "pending-approval" | "approved" | "rejected" | "executed" | "expired";
 /** Dual-control request; the resulting change is always a ledger transaction. */
 interface AdjustmentRequestV1 {
@@ -503,6 +706,88 @@ interface AdjustmentRequestV1 {
 /** Proves that production adjustment approval was performed by another actor. */
 declare function assertDistinctAdjustmentApproval(request: AdjustmentRequestV1): void;
 
+type PaidLotLifecycleStatusV1 = "clear" | "partially-reversed" | "disputed" | "fully-reversed" | "chargeback-lost";
+type PaidLotLifecycleEventTypeV1 = "refund" | "dispute-hold" | "dispute-won" | "dispute-lost" | "chargeback" | "reversal";
+/** Paid-purchase facts not already carried by the source lot. */
+interface PaidLotPurchaseProvenanceV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly purchaseId: string;
+    readonly catalogVersion: string;
+    readonly purchasedAt: IsoTimestamp;
+}
+/** Provider-neutral refund/dispute evidence for a paid source lot. */
+interface PaidLotLifecycleEventV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly eventId: string;
+    readonly lotId: LotId;
+    readonly eventType: PaidLotLifecycleEventTypeV1;
+    readonly amount: TokenSubunitString;
+    readonly occurredAt: IsoTimestamp;
+}
+interface PaidLotLifecycleReceiptV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly event: PaidLotLifecycleEventV1;
+}
+/**
+ * Retained paid-lot projection. Immutable purchase/original facts plus every
+ * receipt are sufficient to rebuild all derived amounts in occurrence order.
+ */
+interface PaidLotLifecycleV1 {
+    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 originalAmount: TokenSubunitString;
+    readonly retainedAmount: TokenSubunitString;
+    readonly heldAmount: TokenSubunitString;
+    readonly reversedAmount: TokenSubunitString;
+    readonly refundedAmount: TokenSubunitString;
+    readonly chargebackAmount: TokenSubunitString;
+    readonly oneTimeReversalAmount: TokenSubunitString;
+    readonly status: PaidLotLifecycleStatusV1;
+    readonly version: number;
+    readonly receipts: readonly PaidLotLifecycleReceiptV1[];
+    readonly effectiveEventIds: readonly string[];
+}
+/** Exact signed projection deltas produced when one receipt is appended. */
+interface PaidLotLifecycleArithmeticV1 {
+    readonly retainedDelta: TokenSubunitString;
+    readonly heldDelta: TokenSubunitString;
+    readonly reversedDelta: TokenSubunitString;
+    readonly refundedDelta: TokenSubunitString;
+    readonly chargebackDelta: TokenSubunitString;
+    readonly oneTimeReversalDelta: TokenSubunitString;
+}
+interface PaidLotLifecycleMutationResultV1 {
+    readonly lifecycle: PaidLotLifecycleV1;
+    /** False only for an exact event-ID replay already recorded. */
+    readonly applied: boolean;
+    readonly stateChanged: boolean;
+    readonly arithmetic: PaidLotLifecycleArithmeticV1;
+}
+/** Validates the paid purchase facts paired with a source lot. */
+declare function assertPaidLotPurchaseProvenance(provenance: PaidLotPurchaseProvenanceV1): void;
+/** Validates one provider-neutral paid-lot lifecycle event. */
+declare function assertPaidLotLifecycleEvent(event: PaidLotLifecycleEventV1): void;
+/** Validates and deterministically rebuilds retained paid-lot arithmetic. */
+declare function assertPaidLotLifecycle(lifecycle: PaidLotLifecycleV1): void;
+/** Creates the retained projection for one newly credited paid source lot. */
+declare function createPaidLotLifecycle(lot: SourceLotV1, provenance: PaidLotPurchaseProvenanceV1): PaidLotLifecycleV1;
+/**
+ * Appends one event then rebuilds every receipt in authoritative occurrence
+ * order. Exact retries succeed before stale-version validation.
+ */
+declare function applyPaidLotLifecycleEvent(lifecycle: PaidLotLifecycleV1, event: PaidLotLifecycleEventV1, expectedVersion: number): PaidLotLifecycleMutationResultV1;
+/** Reduces unordered/retried lifecycle evidence in canonical event order. */
+declare function reducePaidLotLifecycleEvents(initial: PaidLotLifecycleV1, events: readonly PaidLotLifecycleEventV1[]): PaidLotLifecycleV1;
+/** Creates the exact retained-basis input used by early-backer evaluators. */
+declare function createEarlyBackerRetentionFromPaidLot(lifecycle: PaidLotLifecycleV1): PaidLotRetentionV1;
+
 type WalletKind = "household-treasury" | "personal" | "gameplay-allocation" | "hold" | "purchase-clearing" | "provider-clearing" | "system";
 type WalletStatus = "active" | "restricted" | "closed";
 type WalletOwnerType = "account" | "household" | "system";
@@ -926,6 +1211,163 @@ interface EconomyQueryPortV1 {
     listPortfolioActivity(scope: WalletPortfolioReadScopeV1, request: WalletActivityPageRequestV1): Promise<WalletActivityPageV1>;
 }
 
+declare const gbpMinorUnitStringBrand: unique symbol;
+/** Canonical non-negative GBP minor-unit string used by cap contracts. */
+type GbpMinorUnitString = string & {
+    readonly [gbpMinorUnitStringBrand]: "GbpMinorUnitString";
+};
+/** Parses exact GBP minor units without floating point or coercion. */
+declare function parseGbpMinorUnits(value: string): bigint;
+/** Serializes exact GBP minor units using the canonical wire representation. */
+declare function serializeGbpMinorUnits(amount: bigint): GbpMinorUnitString;
+type PurchaseCapScopeTypeV1 = "payer" | "household";
+type PurchaseCapReservationStatusV1 = "reserved" | "settled" | "released" | "expired";
+type PurchaseCapReservationTransitionTypeV1 = "settle" | "release" | "expire";
+interface PurchaseCapReservationTransitionV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly transitionId: string;
+    readonly reservationId: string;
+    readonly transitionType: PurchaseCapReservationTransitionTypeV1;
+    readonly occurredAt: IsoTimestamp;
+}
+/** Append-only cap evidence; effectiveness is rebuilt from occurrence order. */
+interface PurchaseCapReservationTransitionReceiptV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly transition: PurchaseCapReservationTransitionV1;
+}
+/** One purchase amount mirrored into payer and household cap aggregates. */
+interface PurchaseCapReservationV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly reservationId: string;
+    readonly payerAccountId: AccountId;
+    readonly householdId: HouseholdId;
+    readonly priceMinorUnits: GbpMinorUnitString;
+    readonly status: PurchaseCapReservationStatusV1;
+    readonly reservedAt: IsoTimestamp;
+    readonly expiresAt: IsoTimestamp;
+    /** Derived winning transition; every delivery remains in `transitionReceipts`. */
+    readonly finalTransitionId?: string;
+    readonly finalizedAt?: IsoTimestamp;
+    readonly transitionReceipts: readonly PurchaseCapReservationTransitionReceiptV1[];
+}
+/** Optimistic aggregate for exactly one payer or household rolling ceiling. */
+interface RollingPurchaseCapStateV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly scopeType: PurchaseCapScopeTypeV1;
+    readonly scopeId: string;
+    readonly version: number;
+    readonly reservations: readonly PurchaseCapReservationV1[];
+}
+interface ReservePurchaseCapsCommandV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly reservationId: string;
+    readonly payerAccountId: AccountId;
+    readonly householdId: HouseholdId;
+    readonly priceMinorUnits: GbpMinorUnitString;
+    readonly reservedAt: IsoTimestamp;
+    readonly expiresAt: IsoTimestamp;
+    readonly expectedPayerVersion: number;
+    readonly expectedHouseholdVersion: number;
+}
+interface PurchaseCapMutationResultV1 {
+    readonly payerState: RollingPurchaseCapStateV1;
+    readonly householdState: RollingPurchaseCapStateV1;
+    readonly reservation: PurchaseCapReservationV1;
+    /** True when a reservation or transition receipt was newly recorded. */
+    readonly applied: boolean;
+    readonly stateChanged: boolean;
+    readonly payerUsageMinorUnits: GbpMinorUnitString;
+    readonly householdUsageMinorUnits: GbpMinorUnitString;
+}
+/** Validates one rolling-cap transition envelope. */
+declare function assertPurchaseCapReservationTransition(transition: PurchaseCapReservationTransitionV1): void;
+/** Validates one mirrored rolling-cap reservation and its complete rebuild. */
+declare function assertPurchaseCapReservation(reservation: PurchaseCapReservationV1): void;
+/** Validates one payer or household rolling-cap aggregate. */
+declare function assertRollingPurchaseCapState(state: RollingPurchaseCapStateV1): void;
+/** Returns the exact cap usage at one point in time. */
+declare function calculateRollingPurchaseCapUsage(state: RollingPurchaseCapStateV1, checkedAt: IsoTimestamp, policy: PurchaseLimitPolicyV1): GbpMinorUnitString;
+/** Creates an empty compare-and-swap aggregate for one cap scope. */
+declare function createRollingPurchaseCapState(scopeType: PurchaseCapScopeTypeV1, scopeId: string): RollingPurchaseCapStateV1;
+/**
+ * Atomically reserves the same amount in payer and household aggregates.
+ * Adapters must compare-and-swap both returned versions in one transaction.
+ */
+declare function reserveRollingPurchaseCaps(payerState: RollingPurchaseCapStateV1, householdState: RollingPurchaseCapStateV1, command: ReservePurchaseCapsCommandV1, policy: PurchaseLimitPolicyV1): PurchaseCapMutationResultV1;
+/**
+ * Appends a settle/release/expiry receipt and rebuilds authoritative order. A
+ * late-delivered pre-expiry settlement corrects a stored expiry while retaining
+ * both receipts. Payer and household versions still advance atomically.
+ */
+declare function transitionRollingPurchaseCapReservation(payerState: RollingPurchaseCapStateV1, householdState: RollingPurchaseCapStateV1, transition: PurchaseCapReservationTransitionV1, expectedPayerVersion: number, expectedHouseholdVersion: number, policy: PurchaseLimitPolicyV1): PurchaseCapMutationResultV1;
+
+type PurchaseIntentTransitionTypeV1 = "checkout-bound" | "payment-observed" | "credit-recorded" | "expire" | "cancel" | "dispute-opened" | "dispute-won" | "dispute-lost";
+type PurchaseIntentDisputeDispositionV1 = "none" | "open" | "won" | "lost";
+/** Provider-neutral evidence for one requested purchase-intent transition. */
+interface PurchaseIntentTransitionV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly transitionId: string;
+    readonly intentId: string;
+    readonly transitionType: PurchaseIntentTransitionTypeV1;
+    readonly occurredAt: IsoTimestamp;
+    /** Sanitized binding; raw provider checkout references are adapter concerns. */
+    readonly providerCheckoutReferenceHash?: string;
+}
+/** Append-only receipt. Whether it is effective is a rebuildable projection. */
+interface PurchaseIntentTransitionReceiptV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly transition: PurchaseIntentTransitionV1;
+}
+/**
+ * Versioned lifecycle projection. `initialIntent` never changes; every delivery
+ * is rebuilt from its append-only receipts in authoritative occurrence order.
+ */
+interface PurchaseIntentLifecycleV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly initialIntent: PurchaseIntentV1;
+    readonly intent: PurchaseIntentV1;
+    readonly version: number;
+    readonly creditRecorded: boolean;
+    readonly disputeDisposition: PurchaseIntentDisputeDispositionV1;
+    readonly receipts: readonly PurchaseIntentTransitionReceiptV1[];
+    readonly effectiveTransitionIds: readonly string[];
+}
+/** Stable instruction identity for the one permitted purchase credit. */
+interface PurchaseCreditInstructionV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly intentId: string;
+    readonly transitionId: string;
+    readonly idempotencyKey: string;
+}
+interface PurchaseIntentTransitionResultV1 {
+    readonly lifecycle: PurchaseIntentLifecycleV1;
+    /** False only for an exact transition-ID replay already in `receipts`. */
+    readonly recorded: boolean;
+    readonly stateChanged: boolean;
+    readonly creditInstruction?: PurchaseCreditInstructionV1;
+}
+interface PurchaseIntentReductionV1 {
+    readonly lifecycle: PurchaseIntentLifecycleV1;
+    readonly creditInstructions: readonly PurchaseCreditInstructionV1[];
+}
+/** Validates one provider-neutral purchase-intent transition envelope. */
+declare function assertPurchaseIntentTransition(transition: PurchaseIntentTransitionV1): void;
+/** Validates and deterministically rebuilds a lifecycle projection. */
+declare function assertPurchaseIntentLifecycle(lifecycle: PurchaseIntentLifecycleV1, pack: TokenPackV1): void;
+/** Creates a lifecycle from immutable, server-created purchase-intent facts. */
+declare function createPurchaseIntentLifecycle(initialIntent: PurchaseIntentV1, pack: TokenPackV1): PurchaseIntentLifecycleV1;
+/**
+ * Appends one event and rebuilds all receipts by authoritative occurrence time.
+ * A late pre-expiry payment can therefore correct a stored expiry without
+ * deleting the expiry receipt. Exact retries succeed before version checking.
+ */
+declare function applyPurchaseIntentTransition(lifecycle: PurchaseIntentLifecycleV1, transition: PurchaseIntentTransitionV1, expectedVersion: number, pack: TokenPackV1): PurchaseIntentTransitionResultV1;
+/**
+ * Reduces an unordered delivery batch in canonical event-time/type/ID order.
+ * Exact duplicate IDs collapse; conflicting duplicate facts are rejected.
+ */
+declare function reducePurchaseIntentTransitions(initialIntent: PurchaseIntentV1, transitions: readonly PurchaseIntentTransitionV1[], pack: TokenPackV1): PurchaseIntentReductionV1;
+
 type RecurrenceInterval = "daily" | "weekly" | "monthly";
 /** Provider-neutral subscription contract. Site policy controls enablement. */
 interface TokenSubscriptionPlanV1 {
@@ -965,4 +1407,4 @@ interface SpendRequestV1 {
 /** 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 ChainedEconomicJournalTransactionV1, type CreateGameplayAllocationInputV1, EARLY_BACKER_SETTLEMENT_POLICY_V2, ECONOMY_CONTRACT_VERSION, type EarlyBackerEvaluationV1, type EarlyBackerEvaluationV2, type EarlyBackerWindowV1, type EconomicActivityStatusV1, type EconomicJournalStatus, type EconomicJournalTransactionV1, type EconomicWalletActivityEntryV1, type EconomyClockPort, type EconomyCommandEnvelopeV1, type EconomyCommandType, type EconomyCommandWorkflowEventV1, type EconomyCommandWorkflowStateV1, type EconomyContractVersion, EconomyError, type EconomyErrorCode, type EconomyErrorEnvelopeV1, type EconomyIdPort, type EconomyIdempotencyScopeV1, type EconomyOutboxEventV1, type EconomyPersistencePort, type EconomyPersistencePortV2, type EconomyQueryPortV1, type EconomyUnitOfWork, type EconomyUnitOfWorkV2, type FxSnapshotV1, type GameplayAllocationV1, type GameplayLimitsV1, type HouseholdId, type IsoTimestamp, type JournalChainHeadV1, type JournalChainId, 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 ScopedPersistedIdempotencyResultV1, type SourceLotMovementType, type SourceLotMovementV1, 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 VersionedSourceLotV1, type WalletActivityEntryV1, type WalletActivityFilterV1, type WalletActivityPageRequestV1, type WalletActivityPageV1, type WalletActivityStatusV1, type WalletBalanceDeltaV1, type WalletBalanceProjectionV1, type WalletBalanceSummaryV1, type WalletBalanceTotalsV1, type WalletId, type WalletKind, type WalletLifetimeBucket, type WalletLifetimeDeltaV1, type WalletLifetimeSnapshotV1, type WalletLifetimeTotalsV1, type WalletOwnerReferenceV1, type WalletOwnerType, type WalletPortfolioBalanceComponentV1, type WalletPortfolioComponentRole, type WalletPortfolioComponentScopeV1, type WalletPortfolioLifetimeComponentV1, type WalletPortfolioLifetimeV1, type WalletPortfolioReadScopeV1, type WalletPortfolioSummaryV1, type WalletPostingAccountBindingV1, type WalletProjectionBucket, type WalletStatus, type WalletV1, type WorkflowActivityStatusV1, type WorkflowWalletActivityEntryV1, advanceJournalChainHead, applySourceLotMovement, applyTransactionToProjection, applyWalletBalanceDelta, applyWalletLifetimeDeltas, assertActivityEntry, assertBalancedTransaction, assertDeterministicWalletBalanceSummary, assertDistinctAdjustmentApproval, assertEconomicJournalTransaction, assertEconomyCommandEnvelope, assertEconomyCommandWorkflowEvent, assertEconomyIdempotencyScope, assertEconomyIdentifier, assertFlatTokenCatalog, assertFxSnapshot, assertGameplayAllocation, assertJournalChainHead, assertNonNegativeAccounts, assertOpenPurchaseIntent, assertPurchaseIntentBinding, assertPurchaseLimitPolicy, assertReversalAvailable, assertRewardConversion, assertRewardRate, assertScopedPersistedIdempotencyResult, assertSourceLot, assertSourceLotMovement, assertSpendRequest, assertTokenPack, assertTokenReferenceRate, assertTokenSubscriptionPlan, assertVersionedSourceLot, assertWallet, assertWalletActivityEntry, assertWalletActivityPage, assertWalletActivityPageForPortfolio, assertWalletActivityPageRequest, assertWalletBalanceDelta, assertWalletBalanceDeltaBatch, assertWalletBalanceProjection, assertWalletBalanceSummary, assertWalletLifetimeSnapshot, assertWalletLifetimeTotals, assertWalletOwnerReference, assertWalletPortfolioLifetime, assertWalletPortfolioReadScope, assertWalletPortfolioSummary, availableSourceLotAmount, boostGameplayAllocation, canUseSourceLot, canonicalTransactionPayload, convertRewardPayout, createGameplayAllocation, createInitialSourceLotSnapshot, createProjectionSnapshot, createReversalTransaction, createWalletBalanceSummary, createWalletPortfolioLifetime, createWalletPortfolioSummary, deriveWalletBalanceDeltas, deriveWalletLifetimeDeltas, economyAssert, evaluateEarlyBacker, evaluateEarlyBackerBySettlementV2, isWholeTokenAmount, mapBitLabsConversionState, parseIsoTimestamp, parseTokenSubunits, rebuildBalanceProjection, reclaimGameplayAllocation, selectSourceLots, serializeTokenSubunits, sortStringRecord, subunitsToWholeTokens, sumTokenSubunits, toEconomyErrorEnvelope, wholeTokensToSubunits };
+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 ChainedEconomicJournalTransactionV1, type CloseModuleAllowanceInputV1, type CreateGameplayAllocationInputV1, type CreateModuleAllowanceInputV1, type CreateModulePurchaseReceiptInputV1, type CreateModuleSpendHoldInputV1, type CreateModuleSpendQuoteInputV1, EARLY_BACKER_SETTLEMENT_POLICY_V2, ECONOMY_CONTRACT_VERSION, type EarlyBackerEvaluationV1, type EarlyBackerEvaluationV2, type EarlyBackerWindowV1, type EconomicActivityStatusV1, type EconomicJournalStatus, type EconomicJournalTransactionV1, type EconomicWalletActivityEntryV1, type EconomyClockPort, type EconomyCommandEnvelopeV1, type EconomyCommandType, type EconomyCommandWorkflowEventV1, type EconomyCommandWorkflowStateV1, type EconomyContractVersion, EconomyError, type EconomyErrorCode, type EconomyErrorEnvelopeV1, type EconomyIdPort, type EconomyIdempotencyScopeV1, type EconomyOutboxEventV1, type EconomyPersistencePort, type EconomyPersistencePortV2, type EconomyQueryPortV1, type EconomyUnitOfWork, type EconomyUnitOfWorkV2, type FundModuleAllowanceInputV1, type FxSnapshotV1, type GameplayAllocationV1, type GameplayLimitsV1, type GbpMinorUnitString, type HouseholdId, type IsoTimestamp, type JournalChainHeadV1, type JournalChainId, type LearningEntitlementId, type LearningModuleVersionId, type LedgerPostingV1, type LedgerTransactionV1, type LotId, type LotRefundState, type LotTransferPolicy, type LotUseContextV1, type LotUseOperation, MODULE_ALLOWANCE_PURPOSE, type ModuleAllowanceId, type ModuleAllowanceStatusV1, type ModuleAllowanceV1, type ModulePurchaseEntitlementStateV1, type ModulePurchaseFinancialStateV1, type ModulePurchaseReceiptV1, type ModulePurchaseReconciliationActionV1, type ModulePurchaseReconciliationObservationV1, type ModulePurchaseReconciliationResultV1, type ModuleSpendHoldId, type ModuleSpendHoldStatusV1, type ModuleSpendHoldV1, type ModuleSpendQuoteId, type ModuleSpendQuoteV1, type ModuleSpendTransitionResultV1, PRE_UTILITY_BACKER_COHORT, type PaidLotLifecycleArithmeticV1, type PaidLotLifecycleEventTypeV1, type PaidLotLifecycleEventV1, type PaidLotLifecycleMutationResultV1, type PaidLotLifecycleReceiptV1, type PaidLotLifecycleStatusV1, type PaidLotLifecycleV1, type PaidLotPurchaseProvenanceV1, type PaidLotRetentionV1, type PeriodicLimitWindow, type PersistedIdempotencyResultV1, type PostingId, type ProviderEventId, type PurchaseCapMutationResultV1, type PurchaseCapReservationStatusV1, type PurchaseCapReservationTransitionReceiptV1, type PurchaseCapReservationTransitionTypeV1, type PurchaseCapReservationTransitionV1, type PurchaseCapReservationV1, type PurchaseCapScopeTypeV1, type PurchaseCreditInstructionV1, type PurchaseIntentDisputeDispositionV1, type PurchaseIntentLifecycleV1, type PurchaseIntentReductionV1, type PurchaseIntentStatus, type PurchaseIntentTransitionReceiptV1, type PurchaseIntentTransitionResultV1, type PurchaseIntentTransitionTypeV1, type PurchaseIntentTransitionV1, type PurchaseIntentV1, type PurchaseLimitPolicyV1, type ReclaimGameplayAllocationInputV1, type ReclaimModuleAllowanceInputV1, type RecurrenceInterval, type ReleaseModuleSpendHoldInputV1, type ReservePurchaseCapsCommandV1, type ReversalInputV1, type RewardActivityTransitionV1, type RewardConversionStatus, type RewardConversionV1, type RewardRateV1, type RollingPurchaseCapStateV1, type ScopedPersistedIdempotencyResultV1, type SettleModuleSpendHoldInputV1, type SourceLotMovementType, type SourceLotMovementV1, 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 VersionedSourceLotV1, type WalletActivityEntryV1, type WalletActivityFilterV1, type WalletActivityPageRequestV1, type WalletActivityPageV1, type WalletActivityStatusV1, type WalletBalanceDeltaV1, type WalletBalanceProjectionV1, type WalletBalanceSummaryV1, type WalletBalanceTotalsV1, type WalletId, type WalletKind, type WalletLifetimeBucket, type WalletLifetimeDeltaV1, type WalletLifetimeSnapshotV1, type WalletLifetimeTotalsV1, type WalletOwnerReferenceV1, type WalletOwnerType, type WalletPortfolioBalanceComponentV1, type WalletPortfolioComponentRole, type WalletPortfolioComponentScopeV1, type WalletPortfolioLifetimeComponentV1, type WalletPortfolioLifetimeV1, type WalletPortfolioReadScopeV1, type WalletPortfolioSummaryV1, type WalletPostingAccountBindingV1, type WalletProjectionBucket, type WalletStatus, type WalletV1, type WorkflowActivityStatusV1, type WorkflowWalletActivityEntryV1, advanceJournalChainHead, applyPaidLotLifecycleEvent, applyPurchaseIntentTransition, applySourceLotMovement, applyTransactionToProjection, applyWalletBalanceDelta, applyWalletLifetimeDeltas, assertActivityEntry, assertBalancedTransaction, assertDeterministicWalletBalanceSummary, assertDistinctAdjustmentApproval, assertEconomicJournalTransaction, assertEconomyCommandEnvelope, assertEconomyCommandWorkflowEvent, assertEconomyIdempotencyScope, assertEconomyIdentifier, assertFlatTokenCatalog, assertFxSnapshot, assertGameplayAllocation, assertJournalChainHead, assertModuleAllowance, assertModulePurchaseReceipt, assertModulePurchaseReconciliationObservation, assertModuleSpendHold, assertModuleSpendQuote, assertNonNegativeAccounts, assertOpenPurchaseIntent, assertPaidLotLifecycle, assertPaidLotLifecycleEvent, assertPaidLotPurchaseProvenance, assertPurchaseCapReservation, assertPurchaseCapReservationTransition, assertPurchaseIntentBinding, assertPurchaseIntentLifecycle, assertPurchaseIntentTransition, assertPurchaseLimitPolicy, assertReversalAvailable, assertRewardConversion, assertRewardRate, assertRollingPurchaseCapState, assertScopedPersistedIdempotencyResult, assertSourceLot, assertSourceLotMovement, assertSpendRequest, assertTokenPack, assertTokenReferenceRate, assertTokenSubscriptionPlan, assertVersionedSourceLot, assertWallet, assertWalletActivityEntry, assertWalletActivityPage, assertWalletActivityPageForPortfolio, assertWalletActivityPageRequest, assertWalletBalanceDelta, assertWalletBalanceDeltaBatch, assertWalletBalanceProjection, assertWalletBalanceSummary, assertWalletLifetimeSnapshot, assertWalletLifetimeTotals, assertWalletOwnerReference, assertWalletPortfolioLifetime, assertWalletPortfolioReadScope, assertWalletPortfolioSummary, availableSourceLotAmount, boostGameplayAllocation, calculateRollingPurchaseCapUsage, canUseSourceLot, canonicalTransactionPayload, closeModuleAllowance, convertRewardPayout, createEarlyBackerRetentionFromPaidLot, createGameplayAllocation, createInitialSourceLotSnapshot, createModuleAllowance, createModulePurchaseReceipt, createModuleSpendHold, createModuleSpendQuote, createPaidLotLifecycle, createProjectionSnapshot, createPurchaseIntentLifecycle, createReversalTransaction, createRollingPurchaseCapState, createWalletBalanceSummary, createWalletPortfolioLifetime, createWalletPortfolioSummary, deriveWalletBalanceDeltas, deriveWalletLifetimeDeltas, economyAssert, evaluateEarlyBacker, evaluateEarlyBackerBySettlementV2, fundModuleAllowance, isWholeTokenAmount, mapBitLabsConversionState, parseGbpMinorUnits, parseIsoTimestamp, parseTokenSubunits, rebuildBalanceProjection, reclaimGameplayAllocation, reclaimModuleAllowance, reconcileModulePurchase, reducePaidLotLifecycleEvents, reducePurchaseIntentTransitions, releaseModuleSpendHold, reserveRollingPurchaseCaps, selectSourceLots, serializeGbpMinorUnits, serializeTokenSubunits, settleModuleSpendHold, sortStringRecord, subunitsToWholeTokens, sumTokenSubunits, toEconomyErrorEnvelope, transitionRollingPurchaseCapReservation, wholeTokensToSubunits };