@plasius/economy 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -33,6 +33,8 @@ __export(index_exports, {
   TOKEN_SUBUNITS_MIN: () => TOKEN_SUBUNITS_MIN,
   TOKEN_SUBUNITS_PER_TOKEN: () => TOKEN_SUBUNITS_PER_TOKEN,
   advanceJournalChainHead: () => advanceJournalChainHead,
+  applyPaidLotLifecycleEvent: () => applyPaidLotLifecycleEvent,
+  applyPurchaseIntentTransition: () => applyPurchaseIntentTransition,
   applySourceLotMovement: () => applySourceLotMovement,
   applyTransactionToProjection: () => applyTransactionToProjection,
   applyWalletBalanceDelta: () => applyWalletBalanceDelta,
@@ -52,11 +54,19 @@ __export(index_exports, {
   assertJournalChainHead: () => assertJournalChainHead,
   assertNonNegativeAccounts: () => assertNonNegativeAccounts,
   assertOpenPurchaseIntent: () => assertOpenPurchaseIntent,
+  assertPaidLotLifecycle: () => assertPaidLotLifecycle,
+  assertPaidLotLifecycleEvent: () => assertPaidLotLifecycleEvent,
+  assertPaidLotPurchaseProvenance: () => assertPaidLotPurchaseProvenance,
+  assertPurchaseCapReservation: () => assertPurchaseCapReservation,
+  assertPurchaseCapReservationTransition: () => assertPurchaseCapReservationTransition,
   assertPurchaseIntentBinding: () => assertPurchaseIntentBinding,
+  assertPurchaseIntentLifecycle: () => assertPurchaseIntentLifecycle,
+  assertPurchaseIntentTransition: () => assertPurchaseIntentTransition,
   assertPurchaseLimitPolicy: () => assertPurchaseLimitPolicy,
   assertReversalAvailable: () => assertReversalAvailable,
   assertRewardConversion: () => assertRewardConversion,
   assertRewardRate: () => assertRewardRate,
+  assertRollingPurchaseCapState: () => assertRollingPurchaseCapState,
   assertScopedPersistedIdempotencyResult: () => assertScopedPersistedIdempotencyResult,
   assertSourceLot: () => assertSourceLot,
   assertSourceLotMovement: () => assertSourceLotMovement,
@@ -82,13 +92,18 @@ __export(index_exports, {
   assertWalletPortfolioSummary: () => assertWalletPortfolioSummary,
   availableSourceLotAmount: () => availableSourceLotAmount,
   boostGameplayAllocation: () => boostGameplayAllocation,
+  calculateRollingPurchaseCapUsage: () => calculateRollingPurchaseCapUsage,
   canUseSourceLot: () => canUseSourceLot,
   canonicalTransactionPayload: () => canonicalTransactionPayload,
   convertRewardPayout: () => convertRewardPayout,
+  createEarlyBackerRetentionFromPaidLot: () => createEarlyBackerRetentionFromPaidLot,
   createGameplayAllocation: () => createGameplayAllocation,
   createInitialSourceLotSnapshot: () => createInitialSourceLotSnapshot,
+  createPaidLotLifecycle: () => createPaidLotLifecycle,
   createProjectionSnapshot: () => createProjectionSnapshot,
+  createPurchaseIntentLifecycle: () => createPurchaseIntentLifecycle,
   createReversalTransaction: () => createReversalTransaction,
+  createRollingPurchaseCapState: () => createRollingPurchaseCapState,
   createWalletBalanceSummary: () => createWalletBalanceSummary,
   createWalletPortfolioLifetime: () => createWalletPortfolioLifetime,
   createWalletPortfolioSummary: () => createWalletPortfolioSummary,
@@ -99,16 +114,22 @@ __export(index_exports, {
   evaluateEarlyBackerBySettlementV2: () => evaluateEarlyBackerBySettlementV2,
   isWholeTokenAmount: () => isWholeTokenAmount,
   mapBitLabsConversionState: () => mapBitLabsConversionState,
+  parseGbpMinorUnits: () => parseGbpMinorUnits,
   parseIsoTimestamp: () => parseIsoTimestamp,
   parseTokenSubunits: () => parseTokenSubunits,
   rebuildBalanceProjection: () => rebuildBalanceProjection,
   reclaimGameplayAllocation: () => reclaimGameplayAllocation,
+  reducePaidLotLifecycleEvents: () => reducePaidLotLifecycleEvents,
+  reducePurchaseIntentTransitions: () => reducePurchaseIntentTransitions,
+  reserveRollingPurchaseCaps: () => reserveRollingPurchaseCaps,
   selectSourceLots: () => selectSourceLots,
+  serializeGbpMinorUnits: () => serializeGbpMinorUnits,
   serializeTokenSubunits: () => serializeTokenSubunits,
   sortStringRecord: () => sortStringRecord,
   subunitsToWholeTokens: () => subunitsToWholeTokens,
   sumTokenSubunits: () => sumTokenSubunits,
   toEconomyErrorEnvelope: () => toEconomyErrorEnvelope,
+  transitionRollingPurchaseCapReservation: () => transitionRollingPurchaseCapReservation,
   wholeTokensToSubunits: () => wholeTokensToSubunits
 });
 module.exports = __toCommonJS(index_exports);
@@ -196,6 +217,14 @@ function sumTokenSubunits(values) {
   return total;
 }
 
+// src/canonical-order.ts
+function compareUnicodeCodeUnits(left, right) {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
 // src/contracts.ts
 var ECONOMY_CONTRACT_VERSION = "1";
 var IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
@@ -232,7 +261,9 @@ function parseIsoTimestamp(value) {
 }
 function sortStringRecord(value) {
   return Object.fromEntries(
-    Object.entries(value).sort(([left], [right]) => left.localeCompare(right))
+    Object.entries(value).sort(
+      ([left], [right]) => compareUnicodeCodeUnits(left, right)
+    )
   );
 }
 
@@ -1162,7 +1193,9 @@ function assertEconomicJournalTransaction(transaction) {
 }
 function canonicalTransactionPayload(transaction) {
   assertBalancedTransaction(transaction);
-  const postings = [...transaction.postings].sort((left, right) => left.postingId.localeCompare(right.postingId)).map((posting) => ({
+  const postings = [...transaction.postings].sort(
+    (left, right) => compareUnicodeCodeUnits(left.postingId, right.postingId)
+  ).map((posting) => ({
     schemaVersion: posting.schemaVersion,
     postingId: posting.postingId,
     transactionId: posting.transactionId,
@@ -1695,6 +1728,420 @@ function assertDistinctAdjustmentApproval(request) {
   }
 }
 
+// src/paid-lots.ts
+var ZERO_ARITHMETIC = Object.freeze({
+  retainedDelta: serializeTokenSubunits(0n),
+  heldDelta: serializeTokenSubunits(0n),
+  reversedDelta: serializeTokenSubunits(0n),
+  refundedDelta: serializeTokenSubunits(0n),
+  chargebackDelta: serializeTokenSubunits(0n),
+  oneTimeReversalDelta: serializeTokenSubunits(0n)
+});
+var EVENT_TYPES = [
+  "refund",
+  "dispute-hold",
+  "dispute-won",
+  "dispute-lost",
+  "chargeback",
+  "reversal"
+];
+var EVENT_PRECEDENCE = {
+  "dispute-hold": 0,
+  "dispute-won": 1,
+  "dispute-lost": 1,
+  refund: 2,
+  chargeback: 3,
+  reversal: 4
+};
+function assertPaidLotPurchaseProvenance(provenance) {
+  economyAssert(
+    provenance.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported paid-lot provenance contract version"
+  );
+  assertEconomyIdentifier(provenance.purchaseId, "purchaseId");
+  assertEconomyIdentifier(provenance.catalogVersion, "catalogVersion");
+  parseIsoTimestamp(provenance.purchasedAt);
+}
+function assertPaidLotLifecycleEvent(event) {
+  economyAssert(
+    event.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported paid-lot lifecycle event contract version"
+  );
+  assertEconomyIdentifier(event.eventId, "eventId");
+  assertEconomyIdentifier(event.lotId, "lotId");
+  economyAssert(
+    EVENT_TYPES.includes(event.eventType),
+    "INVALID_CONTRACT",
+    "Paid-lot lifecycle event type is unsupported"
+  );
+  economyAssert(
+    parseTokenSubunits(event.amount) > 0n,
+    "INVALID_AMOUNT",
+    "Paid-lot lifecycle event amount must be positive"
+  );
+  parseIsoTimestamp(event.occurredAt);
+}
+function sameEvent(left, right) {
+  return left.schemaVersion === right.schemaVersion && left.eventId === right.eventId && left.lotId === right.lotId && left.eventType === right.eventType && left.amount === right.amount && left.occurredAt === right.occurredAt;
+}
+function compareEvents(left, right) {
+  const timeDifference = parseIsoTimestamp(left.occurredAt) - parseIsoTimestamp(right.occurredAt);
+  if (timeDifference !== 0) {
+    return timeDifference;
+  }
+  const precedenceDifference = EVENT_PRECEDENCE[left.eventType] - EVENT_PRECEDENCE[right.eventType];
+  return precedenceDifference === 0 ? compareUnicodeCodeUnits(left.eventId, right.eventId) : precedenceDifference;
+}
+function deriveStatus(retained, held, reversed, chargeback) {
+  if (held > 0n) {
+    return "disputed";
+  }
+  if (chargeback > 0n) {
+    return "chargeback-lost";
+  }
+  if (retained === 0n) {
+    return "fully-reversed";
+  }
+  return reversed > 0n ? "partially-reversed" : "clear";
+}
+function immutableFactsFromLifecycle(lifecycle) {
+  return {
+    schemaVersion: lifecycle.schemaVersion,
+    lotId: lifecycle.lotId,
+    payerAccountId: lifecycle.payerAccountId,
+    receivingHouseholdId: lifecycle.receivingHouseholdId,
+    purchaseId: lifecycle.purchaseId,
+    catalogVersion: lifecycle.catalogVersion,
+    purchasedAt: lifecycle.purchasedAt,
+    settledAt: lifecycle.settledAt,
+    creditedAt: lifecycle.creditedAt,
+    originalAmount: lifecycle.originalAmount
+  };
+}
+function assertImmutableFacts(facts) {
+  economyAssert(
+    facts.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported paid-lot lifecycle contract version"
+  );
+  assertEconomyIdentifier(facts.lotId, "lotId");
+  assertEconomyIdentifier(facts.payerAccountId, "payerAccountId");
+  assertEconomyIdentifier(
+    facts.receivingHouseholdId,
+    "receivingHouseholdId"
+  );
+  assertEconomyIdentifier(facts.purchaseId, "purchaseId");
+  assertEconomyIdentifier(facts.catalogVersion, "catalogVersion");
+  const purchasedAt = parseIsoTimestamp(facts.purchasedAt);
+  const settledAt = parseIsoTimestamp(facts.settledAt);
+  const creditedAt = parseIsoTimestamp(facts.creditedAt);
+  economyAssert(
+    purchasedAt <= settledAt && settledAt <= creditedAt,
+    "INVALID_TIME_WINDOW",
+    "Paid-lot timestamps must follow purchase, settlement, then credit order"
+  );
+  economyAssert(
+    parseTokenSubunits(facts.originalAmount) > 0n,
+    "INVALID_AMOUNT",
+    "Paid-lot original amount must be positive"
+  );
+}
+function projectPaidLot(facts, receipts) {
+  assertImmutableFacts(facts);
+  const eventIds = /* @__PURE__ */ new Set();
+  let reversalReceipts = 0;
+  for (const receipt of receipts) {
+    economyAssert(
+      receipt.schemaVersion === ECONOMY_CONTRACT_VERSION,
+      "INVALID_CONTRACT",
+      "Unsupported paid-lot receipt contract version"
+    );
+    assertPaidLotLifecycleEvent(receipt.event);
+    economyAssert(
+      receipt.event.lotId === facts.lotId && !eventIds.has(receipt.event.eventId),
+      "DUPLICATE_IDENTIFIER",
+      "Paid-lot receipts must be unique and belong to the lifecycle lot"
+    );
+    eventIds.add(receipt.event.eventId);
+    if (receipt.event.eventType === "reversal") {
+      reversalReceipts += 1;
+    }
+  }
+  economyAssert(
+    reversalReceipts <= 1,
+    "REVERSAL_ALREADY_EXISTS",
+    "Paid-lot lifecycle permits only one distinct reversal event"
+  );
+  let retained = parseTokenSubunits(facts.originalAmount);
+  let held = 0n;
+  let reversed = 0n;
+  let refunded = 0n;
+  let chargeback = 0n;
+  let oneTimeReversal = 0n;
+  const effectiveEventIds = [];
+  for (const receipt of [...receipts].sort(
+    (left, right) => compareEvents(left.event, right.event)
+  )) {
+    const event = receipt.event;
+    economyAssert(
+      parseIsoTimestamp(event.occurredAt) >= parseIsoTimestamp(facts.creditedAt),
+      "INVALID_TIME_WINDOW",
+      "Paid-lot lifecycle event cannot precede credit"
+    );
+    const amount = parseTokenSubunits(event.amount);
+    if (event.eventType === "dispute-hold") {
+      economyAssert(
+        amount <= retained - held,
+        "INSUFFICIENT_ELIGIBLE_LOTS",
+        "Dispute hold exceeds unheld retained paid-lot basis"
+      );
+      held += amount;
+    } else if (event.eventType === "dispute-won") {
+      economyAssert(
+        amount <= held,
+        "INVALID_AMOUNT",
+        "Dispute-win release exceeds held paid-lot basis"
+      );
+      held -= amount;
+    } else if (event.eventType === "dispute-lost") {
+      economyAssert(
+        amount <= held,
+        "INVALID_AMOUNT",
+        "Dispute-loss amount exceeds held paid-lot basis"
+      );
+      held -= amount;
+      retained -= amount;
+      reversed += amount;
+      chargeback += amount;
+    } else {
+      economyAssert(
+        amount <= retained - held,
+        "INSUFFICIENT_ELIGIBLE_LOTS",
+        "Paid-lot reversal exceeds unheld retained basis"
+      );
+      if (event.eventType === "reversal") {
+        oneTimeReversal += amount;
+      } else if (event.eventType === "refund") {
+        refunded += amount;
+      } else {
+        chargeback += amount;
+      }
+      retained -= amount;
+      reversed += amount;
+    }
+    effectiveEventIds.push(event.eventId);
+  }
+  return {
+    retained,
+    held,
+    reversed,
+    refunded,
+    chargeback,
+    oneTimeReversal,
+    status: deriveStatus(retained, held, reversed, chargeback),
+    effectiveEventIds
+  };
+}
+function projectionMatchesLifecycle(projection, lifecycle) {
+  return serializeTokenSubunits(projection.retained) === lifecycle.retainedAmount && serializeTokenSubunits(projection.held) === lifecycle.heldAmount && serializeTokenSubunits(projection.reversed) === lifecycle.reversedAmount && serializeTokenSubunits(projection.refunded) === lifecycle.refundedAmount && serializeTokenSubunits(projection.chargeback) === lifecycle.chargebackAmount && serializeTokenSubunits(projection.oneTimeReversal) === lifecycle.oneTimeReversalAmount && projection.status === lifecycle.status && projection.effectiveEventIds.length === lifecycle.effectiveEventIds.length && projection.effectiveEventIds.every(
+    (eventId, index) => eventId === lifecycle.effectiveEventIds[index]
+  );
+}
+function assertPaidLotLifecycle(lifecycle) {
+  economyAssert(
+    Number.isSafeInteger(lifecycle.version) && lifecycle.version === lifecycle.receipts.length + 1,
+    "INVALID_CONTRACT",
+    "Paid-lot lifecycle version must match its receipt count"
+  );
+  const projection = projectPaidLot(
+    immutableFactsFromLifecycle(lifecycle),
+    lifecycle.receipts
+  );
+  economyAssert(
+    projectionMatchesLifecycle(projection, lifecycle),
+    "INVALID_CONTRACT",
+    "Paid-lot lifecycle does not match its immutable event rebuild"
+  );
+}
+function createPaidLotLifecycle(lot, provenance) {
+  assertSourceLot(lot);
+  assertPaidLotPurchaseProvenance(provenance);
+  economyAssert(
+    lot.payerAccountId !== void 0 && lot.householdId !== void 0,
+    "INVALID_CONTRACT",
+    "Paid-lot lifecycle requires payer and receiving-household provenance"
+  );
+  economyAssert(
+    lot.refundState === "none" && parseTokenSubunits(lot.heldAmount) === 0n && parseTokenSubunits(lot.reversedAmount) === 0n,
+    "INVALID_CONTRACT",
+    "Paid-lot lifecycle must be created before any refund or dispute movement"
+  );
+  economyAssert(
+    parseIsoTimestamp(provenance.purchasedAt) <= parseIsoTimestamp(lot.settledAt),
+    "INVALID_TIME_WINDOW",
+    "Paid purchase time cannot follow settlement"
+  );
+  const facts = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    lotId: lot.lotId,
+    payerAccountId: lot.payerAccountId,
+    receivingHouseholdId: lot.householdId,
+    purchaseId: provenance.purchaseId,
+    catalogVersion: provenance.catalogVersion,
+    purchasedAt: provenance.purchasedAt,
+    settledAt: lot.settledAt,
+    creditedAt: lot.creditedAt,
+    originalAmount: lot.originalAmount
+  };
+  const projection = projectPaidLot(facts, []);
+  const lifecycle = {
+    ...facts,
+    retainedAmount: serializeTokenSubunits(projection.retained),
+    heldAmount: serializeTokenSubunits(projection.held),
+    reversedAmount: serializeTokenSubunits(projection.reversed),
+    refundedAmount: serializeTokenSubunits(projection.refunded),
+    chargebackAmount: serializeTokenSubunits(projection.chargeback),
+    oneTimeReversalAmount: serializeTokenSubunits(
+      projection.oneTimeReversal
+    ),
+    status: projection.status,
+    version: 1,
+    receipts: [],
+    effectiveEventIds: []
+  };
+  assertPaidLotLifecycle(lifecycle);
+  return lifecycle;
+}
+function applyPaidLotLifecycleEvent(lifecycle, event, expectedVersion) {
+  assertPaidLotLifecycle(lifecycle);
+  assertPaidLotLifecycleEvent(event);
+  economyAssert(
+    event.lotId === lifecycle.lotId,
+    "INVALID_CONTRACT",
+    "Paid-lot event belongs to another source lot"
+  );
+  const replay = lifecycle.receipts.find(
+    (receipt) => receipt.event.eventId === event.eventId
+  );
+  if (replay !== void 0) {
+    economyAssert(
+      sameEvent(replay.event, event),
+      "DUPLICATE_IDENTIFIER",
+      "Paid-lot event ID was reused with different facts"
+    );
+    return {
+      lifecycle,
+      applied: false,
+      stateChanged: false,
+      arithmetic: ZERO_ARITHMETIC
+    };
+  }
+  economyAssert(
+    expectedVersion === lifecycle.version,
+    "INVALID_CONTRACT",
+    "Paid-lot lifecycle event has a stale expected version"
+  );
+  const receipts = [
+    ...lifecycle.receipts,
+    { schemaVersion: ECONOMY_CONTRACT_VERSION, event }
+  ];
+  const projection = projectPaidLot(
+    immutableFactsFromLifecycle(lifecycle),
+    receipts
+  );
+  const before = {
+    retained: parseTokenSubunits(lifecycle.retainedAmount),
+    held: parseTokenSubunits(lifecycle.heldAmount),
+    reversed: parseTokenSubunits(lifecycle.reversedAmount),
+    refunded: parseTokenSubunits(lifecycle.refundedAmount),
+    chargeback: parseTokenSubunits(lifecycle.chargebackAmount),
+    oneTimeReversal: parseTokenSubunits(lifecycle.oneTimeReversalAmount)
+  };
+  const next = {
+    ...lifecycle,
+    retainedAmount: serializeTokenSubunits(projection.retained),
+    heldAmount: serializeTokenSubunits(projection.held),
+    reversedAmount: serializeTokenSubunits(projection.reversed),
+    refundedAmount: serializeTokenSubunits(projection.refunded),
+    chargebackAmount: serializeTokenSubunits(projection.chargeback),
+    oneTimeReversalAmount: serializeTokenSubunits(
+      projection.oneTimeReversal
+    ),
+    status: projection.status,
+    version: lifecycle.version + 1,
+    receipts,
+    effectiveEventIds: projection.effectiveEventIds
+  };
+  assertPaidLotLifecycle(next);
+  const arithmetic = {
+    retainedDelta: serializeTokenSubunits(
+      projection.retained - before.retained
+    ),
+    heldDelta: serializeTokenSubunits(projection.held - before.held),
+    reversedDelta: serializeTokenSubunits(
+      projection.reversed - before.reversed
+    ),
+    refundedDelta: serializeTokenSubunits(
+      projection.refunded - before.refunded
+    ),
+    chargebackDelta: serializeTokenSubunits(
+      projection.chargeback - before.chargeback
+    ),
+    oneTimeReversalDelta: serializeTokenSubunits(
+      projection.oneTimeReversal - before.oneTimeReversal
+    )
+  };
+  return {
+    lifecycle: next,
+    applied: true,
+    stateChanged: Object.values(arithmetic).some((delta) => delta !== "0"),
+    arithmetic
+  };
+}
+function reducePaidLotLifecycleEvents(initial, events) {
+  assertPaidLotLifecycle(initial);
+  const unique = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    assertPaidLotLifecycleEvent(event);
+    const existing = unique.get(event.eventId);
+    if (existing !== void 0) {
+      economyAssert(
+        sameEvent(existing, event),
+        "DUPLICATE_IDENTIFIER",
+        "Paid-lot event ID was reused with different facts"
+      );
+    } else {
+      unique.set(event.eventId, event);
+    }
+  }
+  let lifecycle = initial;
+  for (const event of [...unique.values()].sort(compareEvents)) {
+    lifecycle = applyPaidLotLifecycleEvent(
+      lifecycle,
+      event,
+      lifecycle.version
+    ).lifecycle;
+  }
+  return lifecycle;
+}
+function createEarlyBackerRetentionFromPaidLot(lifecycle) {
+  assertPaidLotLifecycle(lifecycle);
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    lotId: lifecycle.lotId,
+    payerAccountId: lifecycle.payerAccountId,
+    receivingHouseholdId: lifecycle.receivingHouseholdId,
+    purchaseId: lifecycle.purchaseId,
+    catalogVersion: lifecycle.catalogVersion,
+    purchasedAt: lifecycle.purchasedAt,
+    settledAt: lifecycle.settledAt,
+    creditedAt: lifecycle.creditedAt,
+    retainedAmount: lifecycle.retainedAmount
+  };
+}
+
 // src/ports/persistence.ts
 function assertScopedPersistedIdempotencyResult(result) {
   economyAssert(
@@ -2762,6 +3209,899 @@ function assertWalletActivityPageForPortfolio(page, scope) {
   );
 }
 
+// src/purchase-caps.ts
+var MAX_SIGNED_BIGINT = 2n ** 63n - 1n;
+var CANONICAL_NON_NEGATIVE_INTEGER = /^(?:0|[1-9][0-9]*)$/u;
+function parseGbpMinorUnits(value) {
+  economyAssert(
+    typeof value === "string" && CANONICAL_NON_NEGATIVE_INTEGER.test(value),
+    "INVALID_AMOUNT",
+    "GBP minor units must be a canonical non-negative integer string"
+  );
+  try {
+    const amount = BigInt(value);
+    economyAssert(
+      amount <= MAX_SIGNED_BIGINT,
+      "AMOUNT_OUT_OF_RANGE",
+      "GBP minor units are outside the signed 64-bit range"
+    );
+    return amount;
+  } catch (error) {
+    if (error instanceof EconomyError) {
+      throw error;
+    }
+    throw new EconomyError("INVALID_AMOUNT", "GBP minor units are invalid");
+  }
+}
+function serializeGbpMinorUnits(amount) {
+  economyAssert(
+    amount >= 0n && amount <= MAX_SIGNED_BIGINT,
+    "AMOUNT_OUT_OF_RANGE",
+    "GBP minor units are outside the signed 64-bit range"
+  );
+  return amount.toString(10);
+}
+var RESERVATION_STATUSES = [
+  "reserved",
+  "settled",
+  "released",
+  "expired"
+];
+var TRANSITION_PRECEDENCE = {
+  settle: 0,
+  release: 1,
+  expire: 2
+};
+function assertPurchaseCapReservationTransition(transition) {
+  economyAssert(
+    transition.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported purchase-cap transition contract version"
+  );
+  assertEconomyIdentifier(transition.transitionId, "transitionId");
+  assertEconomyIdentifier(transition.reservationId, "reservationId");
+  economyAssert(
+    ["settle", "release", "expire"].includes(transition.transitionType),
+    "INVALID_CONTRACT",
+    "Purchase-cap transition type is unsupported"
+  );
+  parseIsoTimestamp(transition.occurredAt);
+}
+function sameTransition(left, right) {
+  return left.schemaVersion === right.schemaVersion && left.transitionId === right.transitionId && left.reservationId === right.reservationId && left.transitionType === right.transitionType && left.occurredAt === right.occurredAt;
+}
+function compareTransitions(left, right) {
+  const timeDifference = parseIsoTimestamp(left.occurredAt) - parseIsoTimestamp(right.occurredAt);
+  if (timeDifference !== 0) {
+    return timeDifference;
+  }
+  const precedenceDifference = TRANSITION_PRECEDENCE[left.transitionType] - TRANSITION_PRECEDENCE[right.transitionType];
+  return precedenceDifference === 0 ? compareUnicodeCodeUnits(left.transitionId, right.transitionId) : precedenceDifference;
+}
+function assertBinding(binding) {
+  economyAssert(
+    binding.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported purchase-cap reservation contract version"
+  );
+  assertEconomyIdentifier(binding.reservationId, "reservationId");
+  assertEconomyIdentifier(binding.payerAccountId, "payerAccountId");
+  assertEconomyIdentifier(binding.householdId, "householdId");
+  economyAssert(
+    parseGbpMinorUnits(binding.priceMinorUnits) > 0n,
+    "INVALID_AMOUNT",
+    "Purchase-cap reservation amount must be positive"
+  );
+  economyAssert(
+    parseIsoTimestamp(binding.expiresAt) > parseIsoTimestamp(binding.reservedAt),
+    "INVALID_TIME_WINDOW",
+    "Purchase-cap reservation expiry must follow its creation"
+  );
+}
+function bindingFromReservation(reservation) {
+  return {
+    schemaVersion: reservation.schemaVersion,
+    reservationId: reservation.reservationId,
+    payerAccountId: reservation.payerAccountId,
+    householdId: reservation.householdId,
+    priceMinorUnits: reservation.priceMinorUnits,
+    reservedAt: reservation.reservedAt,
+    expiresAt: reservation.expiresAt
+  };
+}
+function projectReservation(binding, receipts) {
+  assertBinding(binding);
+  const reservedAt = parseIsoTimestamp(binding.reservedAt);
+  const expiresAt = parseIsoTimestamp(binding.expiresAt);
+  const transitionIds = /* @__PURE__ */ new Set();
+  for (const receipt of receipts) {
+    economyAssert(
+      receipt.schemaVersion === ECONOMY_CONTRACT_VERSION,
+      "INVALID_CONTRACT",
+      "Unsupported purchase-cap transition receipt version"
+    );
+    assertPurchaseCapReservationTransition(receipt.transition);
+    economyAssert(
+      receipt.transition.reservationId === binding.reservationId && !transitionIds.has(receipt.transition.transitionId),
+      "DUPLICATE_IDENTIFIER",
+      "Purchase-cap receipts must be unique and belong to the reservation"
+    );
+    transitionIds.add(receipt.transition.transitionId);
+  }
+  let status = "reserved";
+  let finalTransitionId;
+  let finalizedAt;
+  for (const receipt of [...receipts].sort(
+    (left, right) => compareTransitions(left.transition, right.transition)
+  )) {
+    const transition = receipt.transition;
+    const occurredAt = parseIsoTimestamp(transition.occurredAt);
+    economyAssert(
+      occurredAt >= reservedAt,
+      "INVALID_TIME_WINDOW",
+      "Purchase-cap transition cannot precede reservation"
+    );
+    if (transition.transitionType === "settle") {
+      economyAssert(
+        occurredAt < expiresAt,
+        "INVALID_TIME_WINDOW",
+        "Purchase-cap settlement must use payment time before expiry"
+      );
+    } else if (transition.transitionType === "release") {
+      economyAssert(
+        occurredAt < expiresAt,
+        "INVALID_TIME_WINDOW",
+        "Purchase-cap release must precede reservation expiry"
+      );
+    } else {
+      economyAssert(
+        occurredAt >= expiresAt,
+        "INVALID_TIME_WINDOW",
+        "Purchase-cap reservation cannot expire before its deadline"
+      );
+    }
+    if (status === "reserved") {
+      status = transition.transitionType === "settle" ? "settled" : transition.transitionType === "release" ? "released" : "expired";
+      finalTransitionId = transition.transitionId;
+      finalizedAt = transition.occurredAt;
+    }
+  }
+  return {
+    ...binding,
+    status,
+    ...finalTransitionId === void 0 ? {} : { finalTransitionId, finalizedAt },
+    transitionReceipts: receipts
+  };
+}
+function sameReservationFacts(left, right) {
+  return left.schemaVersion === right.schemaVersion && left.reservationId === right.reservationId && left.payerAccountId === right.payerAccountId && left.householdId === right.householdId && left.priceMinorUnits === right.priceMinorUnits && left.status === right.status && left.reservedAt === right.reservedAt && left.expiresAt === right.expiresAt && left.finalTransitionId === right.finalTransitionId && left.finalizedAt === right.finalizedAt && left.transitionReceipts.length === right.transitionReceipts.length && left.transitionReceipts.every((receipt, index) => {
+    const other = right.transitionReceipts[index];
+    return other !== void 0 && receipt.schemaVersion === other.schemaVersion && sameTransition(receipt.transition, other.transition);
+  });
+}
+function sameReservationBinding(reservation, proposed) {
+  return reservation.schemaVersion === proposed.schemaVersion && reservation.reservationId === proposed.reservationId && reservation.payerAccountId === proposed.payerAccountId && reservation.householdId === proposed.householdId && reservation.priceMinorUnits === proposed.priceMinorUnits && reservation.reservedAt === proposed.reservedAt && reservation.expiresAt === proposed.expiresAt;
+}
+function assertPurchaseCapReservation(reservation) {
+  economyAssert(
+    RESERVATION_STATUSES.includes(reservation.status),
+    "INVALID_CONTRACT",
+    "Purchase-cap reservation status is unsupported"
+  );
+  const projected = projectReservation(
+    bindingFromReservation(reservation),
+    reservation.transitionReceipts
+  );
+  economyAssert(
+    sameReservationFacts(projected, reservation),
+    "INVALID_CONTRACT",
+    "Purchase-cap reservation does not match its immutable event rebuild"
+  );
+}
+function assertRollingPurchaseCapState(state) {
+  economyAssert(
+    state.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported rolling purchase-cap contract version"
+  );
+  economyAssert(
+    state.scopeType === "payer" || state.scopeType === "household",
+    "INVALID_CONTRACT",
+    "Purchase-cap scope type is unsupported"
+  );
+  assertEconomyIdentifier(state.scopeId, "scopeId");
+  const reservationIds = /* @__PURE__ */ new Set();
+  const transitionIds = /* @__PURE__ */ new Set();
+  let receiptCount = 0;
+  for (const reservation of state.reservations) {
+    assertPurchaseCapReservation(reservation);
+    economyAssert(
+      !reservationIds.has(reservation.reservationId),
+      "DUPLICATE_IDENTIFIER",
+      "Purchase-cap state cannot repeat a reservation"
+    );
+    reservationIds.add(reservation.reservationId);
+    economyAssert(
+      state.scopeType === "payer" ? reservation.payerAccountId === state.scopeId : reservation.householdId === state.scopeId,
+      "INVALID_CONTRACT",
+      "Purchase-cap reservation belongs to another aggregate scope"
+    );
+    for (const receipt of reservation.transitionReceipts) {
+      economyAssert(
+        !transitionIds.has(receipt.transition.transitionId),
+        "DUPLICATE_IDENTIFIER",
+        "Purchase-cap state cannot repeat a transition ID"
+      );
+      transitionIds.add(receipt.transition.transitionId);
+      receiptCount += 1;
+    }
+  }
+  economyAssert(
+    Number.isSafeInteger(state.version) && state.version === 1 + state.reservations.length + receiptCount,
+    "INVALID_CONTRACT",
+    "Purchase-cap state version must match reservation and receipt counts"
+  );
+}
+function assertAggregatePair(payerState, householdState, payerAccountId, householdId) {
+  assertRollingPurchaseCapState(payerState);
+  assertRollingPurchaseCapState(householdState);
+  economyAssert(
+    payerState.scopeType === "payer" && payerState.scopeId === payerAccountId && householdState.scopeType === "household" && householdState.scopeId === householdId,
+    "INVALID_CONTRACT",
+    "Purchase-cap aggregate pair does not match payer and household"
+  );
+}
+function findMirroredReservation(payerState, householdState, reservationId) {
+  const payerReservation = payerState.reservations.find(
+    (reservation) => reservation.reservationId === reservationId
+  );
+  const householdReservation = householdState.reservations.find(
+    (reservation) => reservation.reservationId === reservationId
+  );
+  economyAssert(
+    payerReservation === void 0 === (householdReservation === void 0),
+    "INVALID_CONTRACT",
+    "Purchase-cap reservation must exist in both aggregate scopes atomically"
+  );
+  if (payerReservation === void 0 || householdReservation === void 0) {
+    return void 0;
+  }
+  economyAssert(
+    sameReservationFacts(payerReservation, householdReservation),
+    "INVALID_CONTRACT",
+    "Payer and household purchase-cap reservations have diverged"
+  );
+  return payerReservation;
+}
+function windowStart(checkedAt, rollingDays) {
+  return checkedAt - rollingDays * 24 * 60 * 60 * 1e3;
+}
+function calculateRollingPurchaseCapUsage(state, checkedAt, policy) {
+  assertRollingPurchaseCapState(state);
+  assertPurchaseLimitPolicy(policy);
+  const checkedAtValue = parseIsoTimestamp(checkedAt);
+  const start = windowStart(checkedAtValue, policy.rollingDays);
+  let total = 0n;
+  for (const reservation of state.reservations) {
+    if (reservation.status === "reserved" && parseIsoTimestamp(reservation.reservedAt) <= checkedAtValue && checkedAtValue < parseIsoTimestamp(reservation.expiresAt)) {
+      total += parseGbpMinorUnits(reservation.priceMinorUnits);
+    } else if (reservation.status === "settled" && reservation.finalizedAt !== void 0) {
+      const settledAt = parseIsoTimestamp(reservation.finalizedAt);
+      if (settledAt >= start && settledAt <= checkedAtValue) {
+        total += parseGbpMinorUnits(reservation.priceMinorUnits);
+      }
+    }
+    economyAssert(
+      total <= MAX_SIGNED_BIGINT,
+      "AMOUNT_OUT_OF_RANGE",
+      "Rolling purchase-cap usage exceeds signed 64-bit range"
+    );
+  }
+  return serializeGbpMinorUnits(total);
+}
+function createRollingPurchaseCapState(scopeType, scopeId) {
+  economyAssert(
+    scopeType === "payer" || scopeType === "household",
+    "INVALID_CONTRACT",
+    "Purchase-cap scope type is unsupported"
+  );
+  assertEconomyIdentifier(scopeId, "scopeId");
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    scopeType,
+    scopeId,
+    version: 1,
+    reservations: []
+  };
+}
+function sortedWithReservation(state, reservation) {
+  return [...state.reservations, reservation].sort(
+    (left, right) => compareUnicodeCodeUnits(left.reservationId, right.reservationId)
+  );
+}
+function resultWithUsage(payerState, householdState, reservation, applied, stateChanged, checkedAt, policy) {
+  return {
+    payerState,
+    householdState,
+    reservation,
+    applied,
+    stateChanged,
+    payerUsageMinorUnits: calculateRollingPurchaseCapUsage(
+      payerState,
+      checkedAt,
+      policy
+    ),
+    householdUsageMinorUnits: calculateRollingPurchaseCapUsage(
+      householdState,
+      checkedAt,
+      policy
+    )
+  };
+}
+function reserveRollingPurchaseCaps(payerState, householdState, command, policy) {
+  economyAssert(
+    command.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported purchase-cap reservation command version"
+  );
+  const binding = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    reservationId: command.reservationId,
+    payerAccountId: command.payerAccountId,
+    householdId: command.householdId,
+    priceMinorUnits: command.priceMinorUnits,
+    reservedAt: command.reservedAt,
+    expiresAt: command.expiresAt
+  };
+  assertBinding(binding);
+  assertAggregatePair(
+    payerState,
+    householdState,
+    command.payerAccountId,
+    command.householdId
+  );
+  assertPurchaseLimitPolicy(policy);
+  const proposed = projectReservation(binding, []);
+  const replay = findMirroredReservation(
+    payerState,
+    householdState,
+    command.reservationId
+  );
+  if (replay !== void 0) {
+    economyAssert(
+      sameReservationBinding(replay, proposed),
+      "DUPLICATE_IDENTIFIER",
+      "Purchase-cap reservation ID was reused with different facts"
+    );
+    return resultWithUsage(
+      payerState,
+      householdState,
+      replay,
+      false,
+      false,
+      replay.finalizedAt ?? command.reservedAt,
+      policy
+    );
+  }
+  economyAssert(
+    command.expectedPayerVersion === payerState.version && command.expectedHouseholdVersion === householdState.version,
+    "INVALID_CONTRACT",
+    "Purchase-cap reservation has a stale aggregate version"
+  );
+  const amount = parseGbpMinorUnits(command.priceMinorUnits);
+  economyAssert(
+    amount <= parseGbpMinorUnits(policy.maxOrderPriceMinorUnits),
+    "INSUFFICIENT_BALANCE",
+    "Purchase amount exceeds the per-order ceiling"
+  );
+  const payerUsage = parseGbpMinorUnits(
+    calculateRollingPurchaseCapUsage(payerState, command.reservedAt, policy)
+  );
+  const householdUsage = parseGbpMinorUnits(
+    calculateRollingPurchaseCapUsage(
+      householdState,
+      command.reservedAt,
+      policy
+    )
+  );
+  economyAssert(
+    payerUsage + amount <= parseGbpMinorUnits(policy.rollingPayerPriceMinorUnits),
+    "INSUFFICIENT_BALANCE",
+    "Purchase amount exceeds the rolling payer ceiling"
+  );
+  economyAssert(
+    householdUsage + amount <= parseGbpMinorUnits(policy.rollingHouseholdPriceMinorUnits),
+    "INSUFFICIENT_BALANCE",
+    "Purchase amount exceeds the rolling household ceiling"
+  );
+  const nextPayer = {
+    ...payerState,
+    version: payerState.version + 1,
+    reservations: sortedWithReservation(payerState, proposed)
+  };
+  const nextHousehold = {
+    ...householdState,
+    version: householdState.version + 1,
+    reservations: sortedWithReservation(householdState, proposed)
+  };
+  return resultWithUsage(
+    nextPayer,
+    nextHousehold,
+    proposed,
+    true,
+    true,
+    command.reservedAt,
+    policy
+  );
+}
+function replaceReservation(state, replacement) {
+  return {
+    ...state,
+    version: state.version + 1,
+    reservations: state.reservations.map(
+      (reservation) => reservation.reservationId === replacement.reservationId ? replacement : reservation
+    )
+  };
+}
+function findTransitionById(state, transitionId) {
+  for (const reservation of state.reservations) {
+    const receipt = reservation.transitionReceipts.find(
+      (candidate) => candidate.transition.transitionId === transitionId
+    );
+    if (receipt !== void 0) {
+      return { reservationId: reservation.reservationId, transition: receipt.transition };
+    }
+  }
+  return void 0;
+}
+function transitionRollingPurchaseCapReservation(payerState, householdState, transition, expectedPayerVersion, expectedHouseholdVersion, policy) {
+  assertPurchaseCapReservationTransition(transition);
+  assertRollingPurchaseCapState(payerState);
+  assertRollingPurchaseCapState(householdState);
+  const current = findMirroredReservation(
+    payerState,
+    householdState,
+    transition.reservationId
+  );
+  economyAssert(
+    current !== void 0,
+    "INVALID_CONTRACT",
+    "Purchase-cap reservation does not exist in both aggregate scopes"
+  );
+  assertAggregatePair(
+    payerState,
+    householdState,
+    current.payerAccountId,
+    current.householdId
+  );
+  assertPurchaseLimitPolicy(policy);
+  const payerExisting = findTransitionById(
+    payerState,
+    transition.transitionId
+  );
+  const householdExisting = findTransitionById(
+    householdState,
+    transition.transitionId
+  );
+  economyAssert(
+    payerExisting === void 0 === (householdExisting === void 0),
+    "INVALID_CONTRACT",
+    "Purchase-cap transition must exist in both scopes atomically"
+  );
+  if (payerExisting !== void 0 && householdExisting !== void 0) {
+    economyAssert(
+      payerExisting.reservationId === transition.reservationId && householdExisting.reservationId === transition.reservationId && sameTransition(payerExisting.transition, transition) && sameTransition(householdExisting.transition, transition),
+      "DUPLICATE_IDENTIFIER",
+      "Purchase-cap transition ID was reused with different facts"
+    );
+    return resultWithUsage(
+      payerState,
+      householdState,
+      current,
+      false,
+      false,
+      transition.occurredAt,
+      policy
+    );
+  }
+  economyAssert(
+    expectedPayerVersion === payerState.version && expectedHouseholdVersion === householdState.version,
+    "INVALID_CONTRACT",
+    "Purchase-cap transition has a stale aggregate version"
+  );
+  const replacement = projectReservation(bindingFromReservation(current), [
+    ...current.transitionReceipts,
+    { schemaVersion: ECONOMY_CONTRACT_VERSION, transition }
+  ]);
+  const stateChanged = replacement.status !== current.status || replacement.finalTransitionId !== current.finalTransitionId || replacement.finalizedAt !== current.finalizedAt;
+  const nextPayer = replaceReservation(payerState, replacement);
+  const nextHousehold = replaceReservation(householdState, replacement);
+  return resultWithUsage(
+    nextPayer,
+    nextHousehold,
+    replacement,
+    true,
+    stateChanged,
+    transition.occurredAt,
+    policy
+  );
+}
+
+// src/purchase-intents.ts
+var TRANSITION_TYPES = [
+  "checkout-bound",
+  "payment-observed",
+  "credit-recorded",
+  "expire",
+  "cancel",
+  "dispute-opened",
+  "dispute-won",
+  "dispute-lost"
+];
+var TRANSITION_PRECEDENCE2 = {
+  "checkout-bound": 0,
+  "payment-observed": 1,
+  "credit-recorded": 2,
+  "dispute-opened": 3,
+  "dispute-won": 4,
+  "dispute-lost": 4,
+  cancel: 5,
+  expire: 6
+};
+function assertCheckoutHash(value) {
+  economyAssert(
+    /^sha256:[a-f0-9]{64}$/u.test(value),
+    "INVALID_CONTRACT",
+    "Checkout references must be stored as sanitized SHA-256 hashes"
+  );
+}
+function assertPurchaseIntentTransition(transition) {
+  economyAssert(
+    transition.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported purchase-intent transition contract version"
+  );
+  assertEconomyIdentifier(transition.transitionId, "transitionId");
+  assertEconomyIdentifier(transition.intentId, "intentId");
+  economyAssert(
+    TRANSITION_TYPES.includes(transition.transitionType),
+    "INVALID_CONTRACT",
+    "Purchase-intent transition type is unsupported"
+  );
+  parseIsoTimestamp(transition.occurredAt);
+  if (transition.providerCheckoutReferenceHash !== void 0) {
+    assertCheckoutHash(transition.providerCheckoutReferenceHash);
+  }
+  const requiresCheckoutHash = transition.transitionType === "checkout-bound" || transition.transitionType === "payment-observed";
+  economyAssert(
+    requiresCheckoutHash === (transition.providerCheckoutReferenceHash !== void 0),
+    "INVALID_CONTRACT",
+    "Only checkout and payment transitions must carry a checkout binding"
+  );
+}
+function sameTransition2(left, right) {
+  return left.schemaVersion === right.schemaVersion && left.transitionId === right.transitionId && left.intentId === right.intentId && left.transitionType === right.transitionType && left.occurredAt === right.occurredAt && left.providerCheckoutReferenceHash === right.providerCheckoutReferenceHash;
+}
+function sameIntent(left, right) {
+  return left.schemaVersion === right.schemaVersion && left.intentId === right.intentId && left.payerAccountId === right.payerAccountId && left.receivingHouseholdId === right.receivingHouseholdId && left.receivingWalletId === right.receivingWalletId && left.packId === right.packId && left.catalogVersion === right.catalogVersion && left.expectedCurrency === right.expectedCurrency && left.expectedPriceMinorUnits === right.expectedPriceMinorUnits && left.grantAmount === right.grantAmount && left.status === right.status && left.createdAt === right.createdAt && left.expiresAt === right.expiresAt && left.providerCheckoutReferenceHash === right.providerCheckoutReferenceHash;
+}
+function compareTransitions2(left, right) {
+  const timeDifference = parseIsoTimestamp(left.occurredAt) - parseIsoTimestamp(right.occurredAt);
+  if (timeDifference !== 0) {
+    return timeDifference;
+  }
+  const precedenceDifference = TRANSITION_PRECEDENCE2[left.transitionType] - TRANSITION_PRECEDENCE2[right.transitionType];
+  return precedenceDifference === 0 ? compareUnicodeCodeUnits(left.transitionId, right.transitionId) : precedenceDifference;
+}
+function assertMatchingCheckoutBinding(intent, checkoutHash) {
+  economyAssert(
+    intent.providerCheckoutReferenceHash === void 0 || intent.providerCheckoutReferenceHash === checkoutHash,
+    "INVALID_CONTRACT",
+    "Purchase-intent transition conflicts with its checkout binding"
+  );
+}
+function projectPurchaseIntent(initialIntent, transitions, pack) {
+  assertPurchaseIntentBinding(initialIntent, pack);
+  economyAssert(
+    initialIntent.status === "created" && initialIntent.providerCheckoutReferenceHash === void 0,
+    "INVALID_CONTRACT",
+    "Purchase-intent lifecycle requires immutable created intent facts"
+  );
+  const createdAt = parseIsoTimestamp(initialIntent.createdAt);
+  const expiresAt = parseIsoTimestamp(initialIntent.expiresAt);
+  let intent = initialIntent;
+  let disputeDisposition = "none";
+  let creditTransitionId;
+  const effectiveTransitionIds = [];
+  for (const transition of [...transitions].sort(compareTransitions2)) {
+    assertPurchaseIntentTransition(transition);
+    economyAssert(
+      transition.intentId === initialIntent.intentId,
+      "INVALID_CONTRACT",
+      "Purchase-intent transition belongs to another intent"
+    );
+    const eventTime = parseIsoTimestamp(transition.occurredAt);
+    economyAssert(
+      eventTime >= createdAt,
+      "INVALID_TIME_WINDOW",
+      "Purchase-intent transition cannot precede intent creation"
+    );
+    let effective = false;
+    if (transition.transitionType === "checkout-bound") {
+      const checkoutHash = transition.providerCheckoutReferenceHash;
+      assertMatchingCheckoutBinding(intent, checkoutHash);
+      if (intent.status === "created") {
+        economyAssert(
+          eventTime < expiresAt,
+          "INVALID_TIME_WINDOW",
+          "Checkout cannot be bound after purchase-intent expiry"
+        );
+        intent = {
+          ...intent,
+          status: "checkout-created",
+          providerCheckoutReferenceHash: checkoutHash
+        };
+        effective = true;
+      } else {
+        economyAssert(
+          !["expired", "cancelled"].includes(intent.status),
+          "INVALID_CONTRACT",
+          "A terminal purchase intent cannot bind a checkout"
+        );
+      }
+    } else if (transition.transitionType === "payment-observed") {
+      const checkoutHash = transition.providerCheckoutReferenceHash;
+      assertMatchingCheckoutBinding(intent, checkoutHash);
+      economyAssert(
+        eventTime < expiresAt,
+        "INVALID_TIME_WINDOW",
+        "Authoritative payment time must precede purchase-intent expiry"
+      );
+      if (intent.status === "created") {
+        intent = {
+          ...intent,
+          status: "paid-unreconciled",
+          providerCheckoutReferenceHash: checkoutHash
+        };
+        effective = true;
+      } else if (intent.status === "checkout-created") {
+        intent = { ...intent, status: "paid-unreconciled" };
+        effective = true;
+      } else {
+        economyAssert(
+          !["expired", "cancelled"].includes(intent.status),
+          "INVALID_CONTRACT",
+          "A terminal purchase intent cannot observe payment"
+        );
+      }
+    } else if (transition.transitionType === "credit-recorded") {
+      if (intent.status === "paid-unreconciled") {
+        intent = { ...intent, status: "credited" };
+        disputeDisposition = "none";
+        creditTransitionId = transition.transitionId;
+        effective = true;
+      } else {
+        economyAssert(
+          intent.status === "credited" || intent.status === "disputed",
+          "INVALID_CONTRACT",
+          "Purchase intent cannot be credited before authoritative payment"
+        );
+      }
+    } else if (transition.transitionType === "dispute-opened") {
+      if (intent.status === "credited" && disputeDisposition === "none") {
+        intent = { ...intent, status: "disputed" };
+        disputeDisposition = "open";
+        effective = true;
+      } else {
+        economyAssert(
+          intent.status === "disputed" && disputeDisposition === "open",
+          "INVALID_CONTRACT",
+          "Dispute can open only once after purchase credit"
+        );
+      }
+    } else if (transition.transitionType === "dispute-won") {
+      if (intent.status === "disputed" && disputeDisposition === "open") {
+        intent = { ...intent, status: "credited" };
+        disputeDisposition = "won";
+        effective = true;
+      } else {
+        economyAssert(
+          intent.status === "credited" && disputeDisposition === "won",
+          "INVALID_CONTRACT",
+          "Dispute-win transition requires one open dispute"
+        );
+      }
+    } else if (transition.transitionType === "dispute-lost") {
+      if (intent.status === "disputed" && disputeDisposition === "open") {
+        disputeDisposition = "lost";
+        effective = true;
+      } else {
+        economyAssert(
+          intent.status === "disputed" && disputeDisposition === "lost",
+          "INVALID_CONTRACT",
+          "Dispute-loss transition requires one open dispute"
+        );
+      }
+    } else if (transition.transitionType === "cancel") {
+      if (intent.status === "created" || intent.status === "checkout-created") {
+        intent = { ...intent, status: "cancelled" };
+        effective = true;
+      }
+    } else {
+      economyAssert(
+        eventTime >= expiresAt,
+        "INVALID_TIME_WINDOW",
+        "Expiry transition cannot precede purchase-intent expiry"
+      );
+      if (intent.status === "created" || intent.status === "checkout-created") {
+        intent = { ...intent, status: "expired" };
+        effective = true;
+      }
+    }
+    if (effective) {
+      effectiveTransitionIds.push(transition.transitionId);
+    }
+  }
+  return {
+    intent,
+    disputeDisposition,
+    effectiveTransitionIds,
+    ...creditTransitionId === void 0 ? {} : { creditTransitionId }
+  };
+}
+function assertPurchaseIntentLifecycle(lifecycle, pack) {
+  economyAssert(
+    lifecycle.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported purchase-intent lifecycle contract version"
+  );
+  economyAssert(
+    Number.isSafeInteger(lifecycle.version) && lifecycle.version === lifecycle.receipts.length + 1,
+    "INVALID_CONTRACT",
+    "Purchase-intent lifecycle version must match its receipt count"
+  );
+  const transitionIds = /* @__PURE__ */ new Set();
+  for (const receipt of lifecycle.receipts) {
+    economyAssert(
+      receipt.schemaVersion === ECONOMY_CONTRACT_VERSION,
+      "INVALID_CONTRACT",
+      "Purchase-intent receipt is invalid"
+    );
+    assertPurchaseIntentTransition(receipt.transition);
+    economyAssert(
+      receipt.transition.intentId === lifecycle.initialIntent.intentId && !transitionIds.has(receipt.transition.transitionId),
+      "DUPLICATE_IDENTIFIER",
+      "Purchase-intent receipts must be unique and belong to the intent"
+    );
+    transitionIds.add(receipt.transition.transitionId);
+  }
+  const projection = projectPurchaseIntent(
+    lifecycle.initialIntent,
+    lifecycle.receipts.map((receipt) => receipt.transition),
+    pack
+  );
+  economyAssert(
+    sameIntent(projection.intent, lifecycle.intent) && lifecycle.creditRecorded === (projection.intent.status === "credited" || projection.intent.status === "disputed") && lifecycle.disputeDisposition === projection.disputeDisposition && lifecycle.effectiveTransitionIds.length === projection.effectiveTransitionIds.length && lifecycle.effectiveTransitionIds.every(
+      (transitionId, index) => transitionId === projection.effectiveTransitionIds[index]
+    ),
+    "INVALID_CONTRACT",
+    "Purchase-intent lifecycle does not match its immutable event rebuild"
+  );
+}
+function createPurchaseIntentLifecycle(initialIntent, pack) {
+  const projection = projectPurchaseIntent(initialIntent, [], pack);
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    initialIntent,
+    intent: projection.intent,
+    version: 1,
+    creditRecorded: false,
+    disputeDisposition: projection.disputeDisposition,
+    receipts: [],
+    effectiveTransitionIds: []
+  };
+}
+function sameProjection(lifecycle, projection) {
+  return sameIntent(lifecycle.intent, projection.intent) && lifecycle.disputeDisposition === projection.disputeDisposition && lifecycle.effectiveTransitionIds.length === projection.effectiveTransitionIds.length && lifecycle.effectiveTransitionIds.every(
+    (transitionId, index) => transitionId === projection.effectiveTransitionIds[index]
+  );
+}
+function applyPurchaseIntentTransition(lifecycle, transition, expectedVersion, pack) {
+  assertPurchaseIntentLifecycle(lifecycle, pack);
+  assertPurchaseIntentTransition(transition);
+  economyAssert(
+    transition.intentId === lifecycle.initialIntent.intentId,
+    "INVALID_CONTRACT",
+    "Purchase-intent transition belongs to another intent"
+  );
+  const replay = lifecycle.receipts.find(
+    (receipt) => receipt.transition.transitionId === transition.transitionId
+  );
+  if (replay !== void 0) {
+    economyAssert(
+      sameTransition2(replay.transition, transition),
+      "DUPLICATE_IDENTIFIER",
+      "Purchase-intent transition ID was reused with different facts"
+    );
+    return { lifecycle, recorded: false, stateChanged: false };
+  }
+  economyAssert(
+    expectedVersion === lifecycle.version,
+    "INVALID_CONTRACT",
+    "Purchase-intent transition has a stale expected version"
+  );
+  const receipts = [
+    ...lifecycle.receipts,
+    { schemaVersion: ECONOMY_CONTRACT_VERSION, transition }
+  ];
+  const projection = projectPurchaseIntent(
+    lifecycle.initialIntent,
+    receipts.map((receipt) => receipt.transition),
+    pack
+  );
+  const stateChanged = !sameProjection(lifecycle, projection);
+  const nextLifecycle = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    initialIntent: lifecycle.initialIntent,
+    intent: projection.intent,
+    version: lifecycle.version + 1,
+    creditRecorded: projection.intent.status === "credited" || projection.intent.status === "disputed",
+    disputeDisposition: projection.disputeDisposition,
+    receipts,
+    effectiveTransitionIds: projection.effectiveTransitionIds
+  };
+  assertPurchaseIntentLifecycle(nextLifecycle, pack);
+  const producesCredit = projection.creditTransitionId === transition.transitionId && !lifecycle.creditRecorded && nextLifecycle.creditRecorded;
+  const creditInstruction = producesCredit ? {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    intentId: nextLifecycle.intent.intentId,
+    transitionId: transition.transitionId,
+    idempotencyKey: nextLifecycle.intent.intentId
+  } : void 0;
+  return {
+    lifecycle: nextLifecycle,
+    recorded: true,
+    stateChanged,
+    ...creditInstruction === void 0 ? {} : { creditInstruction }
+  };
+}
+function reducePurchaseIntentTransitions(initialIntent, transitions, pack) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const transition of transitions) {
+    assertPurchaseIntentTransition(transition);
+    const existing = unique.get(transition.transitionId);
+    if (existing !== void 0) {
+      economyAssert(
+        sameTransition2(existing, transition),
+        "DUPLICATE_IDENTIFIER",
+        "Purchase-intent transition ID was reused with different facts"
+      );
+    } else {
+      unique.set(transition.transitionId, transition);
+    }
+  }
+  let lifecycle = createPurchaseIntentLifecycle(initialIntent, pack);
+  const creditInstructions = [];
+  for (const transition of [...unique.values()].sort(compareTransitions2)) {
+    const result = applyPurchaseIntentTransition(
+      lifecycle,
+      transition,
+      lifecycle.version,
+      pack
+    );
+    lifecycle = result.lifecycle;
+    if (result.creditInstruction !== void 0) {
+      creditInstructions.push(result.creditInstruction);
+    }
+  }
+  economyAssert(
+    creditInstructions.length <= 1,
+    "DUPLICATE_TRANSACTION",
+    "Purchase-intent reduction produced more than one credit"
+  );
+  return { lifecycle, creditInstructions };
+}
+
 // src/recurrence.ts
 var BASELINE_MONTHLY_SUBSCRIPTION_PLAN = Object.freeze({
   schemaVersion: ECONOMY_CONTRACT_VERSION,
@@ -2900,6 +4240,8 @@ function assertSpendRequest(request) {
   TOKEN_SUBUNITS_MIN,
   TOKEN_SUBUNITS_PER_TOKEN,
   advanceJournalChainHead,
+  applyPaidLotLifecycleEvent,
+  applyPurchaseIntentTransition,
   applySourceLotMovement,
   applyTransactionToProjection,
   applyWalletBalanceDelta,
@@ -2919,11 +4261,19 @@ function assertSpendRequest(request) {
   assertJournalChainHead,
   assertNonNegativeAccounts,
   assertOpenPurchaseIntent,
+  assertPaidLotLifecycle,
+  assertPaidLotLifecycleEvent,
+  assertPaidLotPurchaseProvenance,
+  assertPurchaseCapReservation,
+  assertPurchaseCapReservationTransition,
   assertPurchaseIntentBinding,
+  assertPurchaseIntentLifecycle,
+  assertPurchaseIntentTransition,
   assertPurchaseLimitPolicy,
   assertReversalAvailable,
   assertRewardConversion,
   assertRewardRate,
+  assertRollingPurchaseCapState,
   assertScopedPersistedIdempotencyResult,
   assertSourceLot,
   assertSourceLotMovement,
@@ -2949,13 +4299,18 @@ function assertSpendRequest(request) {
   assertWalletPortfolioSummary,
   availableSourceLotAmount,
   boostGameplayAllocation,
+  calculateRollingPurchaseCapUsage,
   canUseSourceLot,
   canonicalTransactionPayload,
   convertRewardPayout,
+  createEarlyBackerRetentionFromPaidLot,
   createGameplayAllocation,
   createInitialSourceLotSnapshot,
+  createPaidLotLifecycle,
   createProjectionSnapshot,
+  createPurchaseIntentLifecycle,
   createReversalTransaction,
+  createRollingPurchaseCapState,
   createWalletBalanceSummary,
   createWalletPortfolioLifetime,
   createWalletPortfolioSummary,
@@ -2966,16 +4321,22 @@ function assertSpendRequest(request) {
   evaluateEarlyBackerBySettlementV2,
   isWholeTokenAmount,
   mapBitLabsConversionState,
+  parseGbpMinorUnits,
   parseIsoTimestamp,
   parseTokenSubunits,
   rebuildBalanceProjection,
   reclaimGameplayAllocation,
+  reducePaidLotLifecycleEvents,
+  reducePurchaseIntentTransitions,
+  reserveRollingPurchaseCaps,
   selectSourceLots,
+  serializeGbpMinorUnits,
   serializeTokenSubunits,
   sortStringRecord,
   subunitsToWholeTokens,
   sumTokenSubunits,
   toEconomyErrorEnvelope,
+  transitionRollingPurchaseCapReservation,
   wholeTokensToSubunits
 });
 //# sourceMappingURL=index.cjs.map