@plasius/economy 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -39,8 +39,105 @@ 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 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;
+}
+/** Versioned mutable projection around immutable V1 source-lot provenance. */
+interface VersionedSourceLotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly lot: SourceLotV1;
+    readonly version: number;
+    readonly updatedAt: IsoTimestamp;
+}
+type SourceLotMovementType = "allocate" | "boost" | "reclaim" | "spend" | "hold" | "release-hold" | "refund" | "chargeback" | "reversal";
+/**
+ * Immutable movement applied to one source-lot projection by compare-and-swap.
+ * Signed deltas are authoritative; `resultingRefundState` is part of the same
+ * atomic version transition.
+ */
+interface SourceLotMovementV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly movementId: string;
+    readonly transactionId: TransactionId;
+    readonly lotId: LotId;
+    readonly movementType: SourceLotMovementType;
+    readonly remainingDelta: TokenSubunitString;
+    readonly heldDelta: TokenSubunitString;
+    readonly reversedDelta: TokenSubunitString;
+    readonly expectedVersion: number;
+    readonly resultingVersion: number;
+    readonly expectedRefundState: LotRefundState;
+    readonly resultingRefundState: LotRefundState;
+    readonly occurredAt: IsoTimestamp;
+}
+/** Validates source-lot arithmetic, evidence, and immutable provenance fields. */
+declare function assertSourceLot(lot: SourceLotV1): void;
+/** Validates the optimistic projection wrapper used by V2 persistence. */
+declare function assertVersionedSourceLot(snapshot: VersionedSourceLotV1): void;
+/** Creates the only state accepted by the V2 append-source-lot operation. */
+declare function createInitialSourceLotSnapshot(lot: SourceLotV1): VersionedSourceLotV1;
+/** Validates movement shape and operation-specific delta direction. */
+declare function assertSourceLotMovement(movement: SourceLotMovementV1): void;
+/**
+ * Applies one immutable movement to a locked source-lot snapshot. Persistence
+ * must append the movement and compare-and-swap this result atomically.
+ */
+declare function applySourceLotMovement(snapshot: VersionedSourceLotV1, movement: SourceLotMovementV1): VersionedSourceLotV1;
+/** 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 ActivityType = "purchase" | "subscription" | "rewarded-ad" | "offerwall" | "allocation" | "boost" | "reclaim" | "spend" | "hold" | "refund" | "chargeback" | "adjustment" | "reversal" | "event" | "competition";
 type ActivityStatus = "pending" | "held" | "settled" | "reversed" | "failed";
+/**
+ * States permitted on an immutable transaction accepted by the V2
+ * persistence boundary. Pending and failed work belongs to the command
+ * workflow, while a reversed presentation state is derived from an immutable
+ * compensating transaction rather than written back to the original journal
+ * row.
+ */
+type EconomicJournalStatus = "held" | "settled";
+/** A journal transaction that has an immediate economic effect. */
+type EconomicJournalTransactionV1 = Omit<LedgerTransactionV1, "status"> & {
+    readonly status: EconomicJournalStatus;
+};
 /** One signed side of an immutable double-entry transaction. */
 interface LedgerPostingV1 {
     readonly schemaVersion: EconomyContractVersion;
@@ -75,6 +172,8 @@ interface ActivityEntryV1 {
     readonly status: ActivityStatus;
     readonly occurredAt: IsoTimestamp;
     readonly amount: TokenSubunitString;
+    /** Stable source identity used for filtering and provenance presentation. */
+    readonly source: TokenSource;
     readonly beneficiaryAccountId?: AccountId;
     readonly maskedReference?: string;
     readonly sourceLabel: string;
@@ -83,6 +182,11 @@ interface ActivityEntryV1 {
 declare function assertActivityEntry(entry: ActivityEntryV1): void;
 /** Proves the structural and arithmetic invariants of one transaction. */
 declare function assertBalancedTransaction(transaction: LedgerTransactionV1): void;
+/**
+ * Narrows a balanced V1 transaction to the states accepted by the V2 journal.
+ * This is additive: legacy V1 validators retain their existing status union.
+ */
+declare function assertEconomicJournalTransaction(transaction: LedgerTransactionV1): asserts transaction is EconomicJournalTransactionV1;
 /**
  * Produces deterministic UTF-8 JSON for an approved SHA-256/HSM adapter.
  * Hashing itself deliberately remains outside this provider-neutral package.
@@ -217,52 +321,6 @@ declare function convertRewardPayout(providerPayoutMinorUnits: string, rate: Rew
 /** 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 {
@@ -349,11 +407,36 @@ interface EarlyBackerEvaluationV1 {
     readonly contributingLotIds: readonly LotId[];
     readonly evaluatedAt: IsoTimestamp;
 }
+declare const EARLY_BACKER_SETTLEMENT_POLICY_V2: "settlement-window-v2";
+/**
+ * Additive evaluation result using settlement as the sole qualification event.
+ * Purchase and credit times remain provenance/order facts.
+ */
+interface EarlyBackerEvaluationV2 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly policyVersion: typeof EARLY_BACKER_SETTLEMENT_POLICY_V2;
+    readonly qualificationEvent: "settled-at";
+    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;
+/**
+ * Evaluates the approved settlement-window policy. The caller owns environment
+ * and rollout classification: `publicTokensLaunchAt` and
+ * `firstPublicSpendLiveAt` must be derived from the entire public cohort, so
+ * staff, test, and closed-beta availability cannot open or close this window.
+ * The caller must also exclude non-production/test lots before evaluation.
+ */
+declare function evaluateEarlyBackerBySettlementV2(payerAccountId: AccountId, receivingHouseholdId: HouseholdId, paidLots: readonly PaidLotRetentionV1[], window: EarlyBackerWindowV1, evaluatedAt: IsoTimestamp): EarlyBackerEvaluationV2;
 
 /** 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";
@@ -378,6 +461,29 @@ declare function economyAssert(condition: unknown, code: EconomyErrorCode, messa
 /** Creates a bounded, non-sensitive error contract for an HTTP adapter. */
 declare function toEconomyErrorEnvelope(error: EconomyError, requestId?: string): EconomyErrorEnvelopeV1;
 
+type JournalChainId = string;
+/** Locked head of one canonical transaction hash chain. */
+interface JournalChainHeadV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly chainId: JournalChainId;
+    readonly version: number;
+    readonly lastTransactionId?: TransactionId;
+    readonly canonicalHash?: string;
+    readonly updatedAt: IsoTimestamp;
+}
+/** An effective economic transaction carrying its approved canonical hash. */
+type ChainedEconomicJournalTransactionV1 = EconomicJournalTransactionV1 & {
+    readonly canonicalHash: string;
+};
+/** Validates an empty or populated journal-chain head. */
+declare function assertJournalChainHead(head: JournalChainHeadV1): void;
+/**
+ * Proves that a hashed transaction extends the locked head and returns the
+ * exact next head. The persistence adapter must compare-and-swap the old
+ * version inside the same serializable transaction that appends the journal.
+ */
+declare function advanceJournalChainHead(head: JournalChainHeadV1, transaction: ChainedEconomicJournalTransactionV1): JournalChainHeadV1;
+
 type AdjustmentStatus = "draft" | "pending-approval" | "approved" | "rejected" | "executed" | "expired";
 /** Dual-control request; the resulting change is always a ledger transaction. */
 interface AdjustmentRequestV1 {
@@ -397,27 +503,14 @@ interface AdjustmentRequestV1 {
 /** 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";
+/** Exact owner identity used by persistence lookups and IDOR-safe locking. */
+interface WalletOwnerReferenceV1 {
+    readonly ownerType: WalletOwnerType;
+    readonly ownerId: AccountId | HouseholdId | "system";
+}
 /** Versioned authoritative wallet descriptor. */
 interface WalletV1 {
     readonly schemaVersion: EconomyContractVersion;
@@ -453,6 +546,8 @@ interface WalletLifetimeTotalsV1 {
     readonly spent: TokenSubunitString;
     readonly reversed: TokenSubunitString;
 }
+/** Validates an exact wallet owner without accepting a browser-derived role. */
+declare function assertWalletOwnerReference(owner: WalletOwnerReferenceV1): void;
 /** Validates wallet ownership, lifecycle, and optimistic-version facts. */
 declare function assertWallet(wallet: WalletV1): void;
 /** Validates non-negative server-computed wallet balance categories. */
@@ -460,7 +555,89 @@ declare function assertWalletBalanceSummary(summary: WalletBalanceSummaryV1): vo
 /** 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";
+type BalanceProjection = Readonly<Record<AccountId, TokenSubunitString>>;
+interface BalanceProjectionSnapshotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly balances: BalanceProjection;
+    readonly lastTransactionId?: TransactionId;
+    readonly rebuiltAt: IsoTimestamp;
+}
+type WalletProjectionBucket = "spendable" | "reserved" | "held";
+/** Exclusive stored buckets for one wallet; reward progress is derived. */
+interface WalletBalanceProjectionV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly walletId: WalletId;
+    readonly spendable: TokenSubunitString;
+    readonly reserved: TokenSubunitString;
+    readonly held: TokenSubunitString;
+    readonly version: number;
+    readonly lastTransactionId?: TransactionId;
+    readonly asOf: IsoTimestamp;
+}
+/** One atomic add operation against all exclusive buckets of a wallet. */
+interface WalletBalanceDeltaV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly walletId: WalletId;
+    readonly spendableDelta: TokenSubunitString;
+    readonly reservedDelta: TokenSubunitString;
+    readonly heldDelta: TokenSubunitString;
+}
+/** Authoritative mapping from a ledger account to one wallet bucket. */
+interface WalletPostingAccountBindingV1 {
+    readonly accountId: AccountId;
+    readonly walletId: WalletId;
+    readonly bucket: WalletProjectionBucket;
+}
+type WalletLifetimeBucket = "bought" | "earned" | "allocated" | "reclaimed" | "spent" | "reversed";
+/** Positive monotonic contribution to one wallet lifetime counter. */
+interface WalletLifetimeDeltaV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly walletId: WalletId;
+    readonly bucket: WalletLifetimeBucket;
+    readonly amount: TokenSubunitString;
+}
+/** Validates one exclusive-bucket projection. */
+declare function assertWalletBalanceProjection(projection: WalletBalanceProjectionV1): void;
+/** Validates one non-zero atomic wallet delta. */
+declare function assertWalletBalanceDelta(delta: WalletBalanceDeltaV1): void;
+/** Rejects duplicate wallet updates before one atomic persistence call. */
+declare function assertWalletBalanceDeltaBatch(transactionId: TransactionId, deltas: readonly WalletBalanceDeltaV1[]): void;
+/** Applies an atomic add locally for deterministic tests and rebuilds. */
+declare function applyWalletBalanceDelta(projection: WalletBalanceProjectionV1, delta: WalletBalanceDeltaV1, transactionId: TransactionId, asOf: IsoTimestamp): WalletBalanceProjectionV1;
+/**
+ * Converts exclusive storage buckets to the legacy display DTO. Available is
+ * independently usable whole Tokens in this wallet; rewardProgress is this
+ * wallet's sub-Token remainder and is never netted with another wallet.
+ */
+declare function createWalletBalanceSummary(projection: WalletBalanceProjectionV1): WalletBalanceSummaryV1;
+/** Enforces the stronger per-wallet semantics required by V1 query adapters. */
+declare function assertDeterministicWalletBalanceSummary(summary: WalletBalanceSummaryV1): void;
+/**
+ * Derives a single delta per wallet from wallet-linked postings and an
+ * authoritative account-to-bucket mapping. Unlinked system postings are not
+ * wallet projections.
+ */
+declare function deriveWalletBalanceDeltas(transaction: EconomicJournalTransactionV1, bindings: readonly WalletPostingAccountBindingV1[]): readonly WalletBalanceDeltaV1[];
+/**
+ * Rebuilds monotonic gross lifetime contributions from a settled transaction.
+ * Earlier bought/earned counters are never reduced by a later compensating
+ * transaction; removals accrue separately in `reversed`.
+ */
+declare function deriveWalletLifetimeDeltas(transaction: EconomicJournalTransactionV1): readonly WalletLifetimeDeltaV1[];
+/** Applies positive lifetime deltas for one wallet without rewriting history. */
+declare function applyWalletLifetimeDeltas(current: WalletLifetimeTotalsV1, walletId: WalletId, deltas: readonly WalletLifetimeDeltaV1[]): WalletLifetimeTotalsV1;
+/** 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 EconomyCommandType = "credit-purchase" | "credit-subscription" | "credit-reward" | "credit-event" | "credit-competition" | "allocate" | "boost" | "reclaim" | "spend" | "hold" | "release-hold" | "refund" | "chargeback" | "reverse" | "adjust";
 interface EconomyCommandEnvelopeV1 {
     readonly schemaVersion: EconomyContractVersion;
     readonly commandId: string;
@@ -475,6 +652,17 @@ interface EconomyCommandEnvelopeV1 {
     readonly acceptedRegion: string;
     readonly writerFencingToken: string;
 }
+type EconomyCommandWorkflowStateV1 = "accepted" | "processing" | "failed" | "completed";
+/** Immutable workflow evidence; it is never an economic journal transaction. */
+interface EconomyCommandWorkflowEventV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly workflowEventId: string;
+    readonly commandId: string;
+    readonly state: EconomyCommandWorkflowStateV1;
+    /** Stable non-sensitive classifier; detailed failure data stays operational. */
+    readonly failureCode?: string;
+    readonly occurredAt: IsoTimestamp;
+}
 interface EconomyOutboxEventV1 {
     readonly schemaVersion: EconomyContractVersion;
     readonly eventId: string;
@@ -488,6 +676,27 @@ interface PersistedIdempotencyResultV1 {
     readonly responseHash: string;
     readonly recordedAt: IsoTimestamp;
 }
+/** Exact actor/subject/operation namespace for a caller-owned idempotency key. */
+interface EconomyIdempotencyScopeV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly idempotencyKey: string;
+    readonly commandType: EconomyCommandType;
+    readonly actorAccountId: AccountId;
+    readonly subjectAccountId: AccountId;
+}
+/** V2 replay evidence bound to one accepted command and exact scope. */
+interface ScopedPersistedIdempotencyResultV1 extends PersistedIdempotencyResultV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly commandId: string;
+}
+/** Validates replay evidence before it is returned across a command boundary. */
+declare function assertScopedPersistedIdempotencyResult(result: ScopedPersistedIdempotencyResultV1): void;
+/** Validates the namespace that prevents cross-principal replay collisions. */
+declare function assertEconomyIdempotencyScope(scope: EconomyIdempotencyScopeV1): void;
+/** Validates minimized accepted-command evidence before durable append. */
+declare function assertEconomyCommandEnvelope(envelope: EconomyCommandEnvelopeV1): void;
+/** Validates one immutable command-workflow state event. */
+declare function assertEconomyCommandWorkflowEvent(event: EconomyCommandWorkflowEventV1): void;
 /** Operations available only inside one serializable database transaction. */
 interface EconomyUnitOfWork {
     getWalletForUpdate(walletId: WalletId): Promise<WalletV1 | null>;
@@ -509,6 +718,62 @@ interface EconomyPersistencePort {
     getTransaction(transactionId: TransactionId): Promise<LedgerTransactionV1 | null>;
     rebuildProjection(): Promise<BalanceProjection>;
 }
+/**
+ * V2 mutation surface. Unlike `EconomyUnitOfWork`, it has no absolute balance
+ * overwrite: journal, source-lot movement, allocation state, balance/lifetime
+ * deltas, idempotency, chain head, and outbox are committed atomically.
+ */
+interface EconomyUnitOfWorkV2 {
+    getWalletForOwnerForUpdate(walletId: WalletId, owner: WalletOwnerReferenceV1): Promise<WalletV1 | null>;
+    listSpendableLotsForUpdate(walletId: WalletId): Promise<readonly VersionedSourceLotV1[]>;
+    findLotForUpdate(lotId: LotId): Promise<VersionedSourceLotV1 | null>;
+    getGameplayAllocationForUpdate(allocationId: AllocationId, householdId: HouseholdId, childAccountId: AccountId): Promise<GameplayAllocationV1 | null>;
+    findIdempotencyResult(scope: EconomyIdempotencyScopeV1): Promise<ScopedPersistedIdempotencyResultV1 | null>;
+    /** Locks and rejects any stale/non-active regional writer lease. */
+    lockActiveWriterFence(acceptedRegion: string, writerFencingToken: string): Promise<void>;
+    lockJournalChainHead(chainId: string): Promise<JournalChainHeadV1>;
+    appendCommandEnvelope(envelope: EconomyCommandEnvelopeV1): Promise<void>;
+    appendCommandWorkflowEvent(event: EconomyCommandWorkflowEventV1): Promise<void>;
+    appendTransaction(transaction: ChainedEconomicJournalTransactionV1): Promise<void>;
+    /** Appends `createInitialSourceLotSnapshot()` output; later changes are movements. */
+    appendSourceLot(snapshot: VersionedSourceLotV1): Promise<void>;
+    /** Appends movement evidence and applies its lot CAS as one operation. */
+    applySourceLotMovement(movement: SourceLotMovementV1): Promise<void>;
+    appendGameplayAllocation(allocation: GameplayAllocationV1): Promise<void>;
+    /**
+     * Compares `expectedVersion`, requires `allocation.version` to be exactly the
+     * next value, and never overwrites a stale row.
+     */
+    saveGameplayAllocation(allocation: GameplayAllocationV1, expectedVersion: number): Promise<void>;
+    /**
+     * Atomically adds deltas, verifies them against the appended postings and
+     * account bindings, and records transaction-scoped application keys.
+     */
+    applyWalletBalanceDeltas(transactionId: TransactionId, deltas: readonly WalletBalanceDeltaV1[]): Promise<void>;
+    /**
+     * Atomically increments monotonic lifetime counters after verifying the
+     * deltas against the appended transaction's deterministic classification.
+     */
+    applyWalletLifetimeDeltas(transactionId: TransactionId, deltas: readonly WalletLifetimeDeltaV1[]): Promise<void>;
+    saveIdempotencyResult(scope: EconomyIdempotencyScopeV1, result: ScopedPersistedIdempotencyResultV1): Promise<void>;
+    appendOutboxEvent(event: EconomyOutboxEventV1): Promise<void>;
+    /** Compare-and-swaps the full locked head, including its canonical hash. */
+    advanceJournalChainHead(expected: JournalChainHeadV1, next: JournalChainHeadV1): Promise<void>;
+}
+/**
+ * Additive authoritative persistence boundary for new consumers. V1 remains
+ * exported for compatibility but must not be adapted by delegating its
+ * absolute `saveBalanceProjection` operation to this interface.
+ */
+interface EconomyPersistencePortV2 {
+    runSerializable<T>(operation: (unitOfWork: EconomyUnitOfWorkV2) => Promise<T>): Promise<T>;
+    getWallet(walletId: WalletId): Promise<WalletV1 | null>;
+    listWalletsByOwner(owner: WalletOwnerReferenceV1): Promise<readonly WalletV1[]>;
+    getGameplayAllocation(allocationId: AllocationId, householdId: HouseholdId, childAccountId: AccountId): Promise<GameplayAllocationV1 | null>;
+    getCommandEnvelope(commandId: string): Promise<EconomyCommandEnvelopeV1 | null>;
+    getTransaction(transactionId: TransactionId): Promise<ChainedEconomicJournalTransactionV1 | null>;
+    rebuildWalletBalanceProjections(): Promise<readonly WalletBalanceProjectionV1[]>;
+}
 interface EconomyClockPort {
     now(): IsoTimestamp;
 }
@@ -516,6 +781,151 @@ interface EconomyIdPort {
     nextId(namespace: string): string;
 }
 
+type WalletPortfolioComponentRole = "household-treasury" | "personal" | "gameplay-allocation" | "hold";
+/** One server-authorized component of a portfolio read. */
+interface WalletPortfolioComponentScopeV1 {
+    readonly walletId: WalletId;
+    readonly role: WalletPortfolioComponentRole;
+    readonly beneficiaryAccountId?: AccountId;
+}
+/**
+ * Explicit portfolio scope assembled after authorization. It prevents a host's
+ * household treasury and same-user-only personal wallet from being silently
+ * represented as one wallet.
+ */
+interface WalletPortfolioReadScopeV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly portfolioId: string;
+    readonly subjectAccountId: AccountId;
+    readonly components: readonly WalletPortfolioComponentScopeV1[];
+}
+interface WalletBalanceTotalsV1 {
+    readonly available: TokenSubunitString;
+    readonly reserved: TokenSubunitString;
+    readonly held: TokenSubunitString;
+    readonly rewardProgress: TokenSubunitString;
+}
+interface WalletPortfolioBalanceComponentV1 extends WalletPortfolioComponentScopeV1 {
+    readonly summary: WalletBalanceSummaryV1;
+}
+interface WalletPortfolioSummaryV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly portfolioId: string;
+    readonly subjectAccountId: AccountId;
+    readonly components: readonly WalletPortfolioBalanceComponentV1[];
+    /**
+     * Exact column sums for display only. Progress is intentionally not promoted
+     * across wallets because their source/transfer policies may differ.
+     */
+    readonly totals: WalletBalanceTotalsV1;
+    readonly asOf: IsoTimestamp;
+}
+/** Self-identifying lifetime read for one wallet. */
+interface WalletLifetimeSnapshotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly walletId: WalletId;
+    readonly totals: WalletLifetimeTotalsV1;
+    readonly version: number;
+    readonly asOf: IsoTimestamp;
+}
+interface WalletPortfolioLifetimeComponentV1 extends WalletPortfolioComponentScopeV1 {
+    readonly snapshot: WalletLifetimeSnapshotV1;
+}
+interface WalletPortfolioLifetimeV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly portfolioId: string;
+    readonly subjectAccountId: AccountId;
+    readonly components: readonly WalletPortfolioLifetimeComponentV1[];
+    readonly totals: WalletLifetimeTotalsV1;
+    readonly asOf: IsoTimestamp;
+}
+type EconomicActivityStatusV1 = "held" | "settled" | "reversed";
+type WorkflowActivityStatusV1 = "pending" | "failed";
+type WalletActivityStatusV1 = EconomicActivityStatusV1 | WorkflowActivityStatusV1;
+interface WalletActivityBaseV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly activityId: string;
+    /** Component wallet whose signed display amount this row represents. */
+    readonly walletId: WalletId;
+    readonly activityType: ActivityType;
+    readonly occurredAt: IsoTimestamp;
+    readonly amount: TokenSubunitString;
+    readonly source: TokenSource;
+    readonly beneficiaryAccountId?: AccountId;
+    readonly maskedReference?: string;
+    readonly sourceLabel: string;
+}
+/** Economically effective or read-model-derived reversal activity. */
+interface EconomicWalletActivityEntryV1 extends WalletActivityBaseV1 {
+    readonly entryKind: "economic";
+    readonly transactionId: TransactionId;
+    readonly status: EconomicActivityStatusV1;
+}
+/**
+ * Non-economic accepted/failed work. Its amount is display context only and is
+ * excluded from balances and lifetime aggregates.
+ */
+interface WorkflowWalletActivityEntryV1 extends WalletActivityBaseV1 {
+    readonly entryKind: "workflow";
+    readonly commandId: string;
+    readonly status: WorkflowActivityStatusV1;
+}
+type WalletActivityEntryV1 = EconomicWalletActivityEntryV1 | WorkflowWalletActivityEntryV1;
+interface WalletActivityFilterV1 {
+    readonly activityTypes?: readonly ActivityType[];
+    readonly statuses?: readonly WalletActivityStatusV1[];
+    readonly sources?: readonly TokenSource[];
+    readonly beneficiaryAccountId?: AccountId;
+    readonly fromInclusive?: IsoTimestamp;
+    readonly toExclusive?: IsoTimestamp;
+}
+interface WalletActivityPageRequestV1 {
+    readonly limit: number;
+    readonly cursor?: string;
+    readonly filter?: WalletActivityFilterV1;
+}
+interface WalletActivityPageV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly entries: readonly WalletActivityEntryV1[];
+    readonly hasMore: boolean;
+    readonly nextCursor?: string;
+}
+/** Validates a server-created, bounded portfolio scope. */
+declare function assertWalletPortfolioReadScope(scope: WalletPortfolioReadScopeV1): void;
+/** Validates a self-identifying wallet lifetime read. */
+declare function assertWalletLifetimeSnapshot(snapshot: WalletLifetimeSnapshotV1): void;
+/**
+ * Constructs a portfolio balance without merging wallet identities or
+ * promoting sub-Token progress across policy boundaries.
+ */
+declare function createWalletPortfolioSummary(scope: WalletPortfolioReadScopeV1, components: readonly WalletPortfolioBalanceComponentV1[], asOf: IsoTimestamp): WalletPortfolioSummaryV1;
+/** Validates a portfolio balance read independently of its producing adapter. */
+declare function assertWalletPortfolioSummary(summary: WalletPortfolioSummaryV1): void;
+/** Builds monotonic lifetime totals while retaining per-wallet components. */
+declare function createWalletPortfolioLifetime(scope: WalletPortfolioReadScopeV1, components: readonly WalletPortfolioLifetimeComponentV1[], asOf: IsoTimestamp): WalletPortfolioLifetimeV1;
+/** Validates a portfolio lifetime read independently of its producing adapter. */
+declare function assertWalletPortfolioLifetime(lifetime: WalletPortfolioLifetimeV1): void;
+/** Validates the economic/workflow activity discriminant and safe display data. */
+declare function assertWalletActivityEntry(entry: WalletActivityEntryV1): void;
+/** Validates bounded filters and opaque cursor input. */
+declare function assertWalletActivityPageRequest(request: WalletActivityPageRequestV1): void;
+/**
+ * Validates stable descending `(occurredAt, activityId)` page order and cursor
+ * presence. Cursors remain opaque to this provider-neutral package.
+ */
+declare function assertWalletActivityPage(page: WalletActivityPageV1): void;
+/** Prevents an activity cursor/result from expanding an authorized portfolio. */
+declare function assertWalletActivityPageForPortfolio(page: WalletActivityPageV1, scope: WalletPortfolioReadScopeV1): void;
+/** Read-only adapter boundary; authorization must precede scope construction. */
+interface EconomyQueryPortV1 {
+    getWalletSummary(walletId: WalletId): Promise<WalletBalanceSummaryV1 | null>;
+    getWalletLifetime(walletId: WalletId): Promise<WalletLifetimeSnapshotV1 | null>;
+    listWalletActivity(walletId: WalletId, request: WalletActivityPageRequestV1): Promise<WalletActivityPageV1>;
+    getPortfolioSummary(scope: WalletPortfolioReadScopeV1): Promise<WalletPortfolioSummaryV1>;
+    getPortfolioLifetime(scope: WalletPortfolioReadScopeV1): Promise<WalletPortfolioLifetimeV1>;
+    listPortfolioActivity(scope: WalletPortfolioReadScopeV1, request: WalletActivityPageRequestV1): Promise<WalletActivityPageV1>;
+}
+
 type RecurrenceInterval = "daily" | "weekly" | "monthly";
 /** Provider-neutral subscription contract. Site policy controls enablement. */
 interface TokenSubscriptionPlanV1 {
@@ -555,4 +965,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 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 };
+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 };