@plasius/economy 0.3.2 → 0.4.0

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   EARLY_BACKER_SETTLEMENT_POLICY_V2: () => EARLY_BACKER_SETTLEMENT_POLICY_V2,
   ECONOMY_CONTRACT_VERSION: () => ECONOMY_CONTRACT_VERSION,
   EconomyError: () => EconomyError,
+  MODULE_ALLOWANCE_PURPOSE: () => MODULE_ALLOWANCE_PURPOSE,
   PRE_UTILITY_BACKER_COHORT: () => PRE_UTILITY_BACKER_COHORT,
   TOKEN_SUBUNITS_MAX: () => TOKEN_SUBUNITS_MAX,
   TOKEN_SUBUNITS_MIN: () => TOKEN_SUBUNITS_MIN,
@@ -52,6 +53,11 @@ __export(index_exports, {
   assertFxSnapshot: () => assertFxSnapshot,
   assertGameplayAllocation: () => assertGameplayAllocation,
   assertJournalChainHead: () => assertJournalChainHead,
+  assertModuleAllowance: () => assertModuleAllowance,
+  assertModulePurchaseReceipt: () => assertModulePurchaseReceipt,
+  assertModulePurchaseReconciliationObservation: () => assertModulePurchaseReconciliationObservation,
+  assertModuleSpendHold: () => assertModuleSpendHold,
+  assertModuleSpendQuote: () => assertModuleSpendQuote,
   assertNonNegativeAccounts: () => assertNonNegativeAccounts,
   assertOpenPurchaseIntent: () => assertOpenPurchaseIntent,
   assertPaidLotLifecycle: () => assertPaidLotLifecycle,
@@ -95,10 +101,15 @@ __export(index_exports, {
   calculateRollingPurchaseCapUsage: () => calculateRollingPurchaseCapUsage,
   canUseSourceLot: () => canUseSourceLot,
   canonicalTransactionPayload: () => canonicalTransactionPayload,
+  closeModuleAllowance: () => closeModuleAllowance,
   convertRewardPayout: () => convertRewardPayout,
   createEarlyBackerRetentionFromPaidLot: () => createEarlyBackerRetentionFromPaidLot,
   createGameplayAllocation: () => createGameplayAllocation,
   createInitialSourceLotSnapshot: () => createInitialSourceLotSnapshot,
+  createModuleAllowance: () => createModuleAllowance,
+  createModulePurchaseReceipt: () => createModulePurchaseReceipt,
+  createModuleSpendHold: () => createModuleSpendHold,
+  createModuleSpendQuote: () => createModuleSpendQuote,
   createPaidLotLifecycle: () => createPaidLotLifecycle,
   createProjectionSnapshot: () => createProjectionSnapshot,
   createPurchaseIntentLifecycle: () => createPurchaseIntentLifecycle,
@@ -112,6 +123,7 @@ __export(index_exports, {
   economyAssert: () => economyAssert,
   evaluateEarlyBacker: () => evaluateEarlyBacker,
   evaluateEarlyBackerBySettlementV2: () => evaluateEarlyBackerBySettlementV2,
+  fundModuleAllowance: () => fundModuleAllowance,
   isWholeTokenAmount: () => isWholeTokenAmount,
   mapBitLabsConversionState: () => mapBitLabsConversionState,
   parseGbpMinorUnits: () => parseGbpMinorUnits,
@@ -119,12 +131,16 @@ __export(index_exports, {
   parseTokenSubunits: () => parseTokenSubunits,
   rebuildBalanceProjection: () => rebuildBalanceProjection,
   reclaimGameplayAllocation: () => reclaimGameplayAllocation,
+  reclaimModuleAllowance: () => reclaimModuleAllowance,
+  reconcileModulePurchase: () => reconcileModulePurchase,
   reducePaidLotLifecycleEvents: () => reducePaidLotLifecycleEvents,
   reducePurchaseIntentTransitions: () => reducePurchaseIntentTransitions,
+  releaseModuleSpendHold: () => releaseModuleSpendHold,
   reserveRollingPurchaseCaps: () => reserveRollingPurchaseCaps,
   selectSourceLots: () => selectSourceLots,
   serializeGbpMinorUnits: () => serializeGbpMinorUnits,
   serializeTokenSubunits: () => serializeTokenSubunits,
+  settleModuleSpendHold: () => settleModuleSpendHold,
   sortStringRecord: () => sortStringRecord,
   subunitsToWholeTokens: () => subunitsToWholeTokens,
   sumTokenSubunits: () => sumTokenSubunits,
@@ -1682,6 +1698,682 @@ function selectSourceLots(lots, requestedAmount, context) {
   );
 }
 
+// src/module-allowances.ts
+var MODULE_ALLOWANCE_PURPOSE = "junior-coder-module-entitlement";
+function assertWholePositive2(amount, label) {
+  const parsed = parseTokenSubunits(amount);
+  economyAssert(parsed > 0n, "INVALID_AMOUNT", `${label} must be positive`);
+  economyAssert(
+    isWholeTokenAmount(parsed),
+    "AMOUNT_NOT_WHOLE_TOKEN",
+    `${label} must contain whole Tokens`
+  );
+  return parsed;
+}
+function assertPositiveSlices(slices, expectedAmount, label) {
+  economyAssert(slices.length > 0, "INVALID_CONTRACT", `${label} are required`);
+  const lotIds = /* @__PURE__ */ new Set();
+  for (const slice of slices) {
+    assertEconomyIdentifier(slice.lotId, "lotId");
+    economyAssert(
+      !lotIds.has(slice.lotId),
+      "DUPLICATE_IDENTIFIER",
+      `${label} must not repeat a lot`
+    );
+    lotIds.add(slice.lotId);
+    economyAssert(
+      parseTokenSubunits(slice.amount) > 0n,
+      "INVALID_AMOUNT",
+      `${label} amounts must be positive`
+    );
+  }
+  economyAssert(
+    sumTokenSubunits(slices.map((slice) => slice.amount)) === expectedAmount,
+    "INVALID_CONTRACT",
+    `${label} must sum to the operation amount`
+  );
+}
+function sumSlicesByLot(slices) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const slice of slices) {
+    assertEconomyIdentifier(slice.lotId, "lotId");
+    const amount = parseTokenSubunits(slice.amount);
+    economyAssert(amount > 0n, "INVALID_AMOUNT", "Lot slices must be positive");
+    totals.set(slice.lotId, (totals.get(slice.lotId) ?? 0n) + amount);
+  }
+  return totals;
+}
+function assertSha256Reference(value, label) {
+  economyAssert(
+    typeof value === "string" && /^sha256:[a-f0-9]{64}$/u.test(value),
+    "INVALID_CONTRACT",
+    `${label} must be a canonical SHA-256 reference`
+  );
+}
+function assertUpdatedAt(current, occurredAt, label) {
+  economyAssert(
+    parseIsoTimestamp(occurredAt) >= parseIsoTimestamp(current),
+    "INVALID_TIME_WINDOW",
+    `${label} cannot precede the current state`
+  );
+}
+function assertModuleAllowance(allowance) {
+  economyAssert(
+    allowance.schemaVersion === ECONOMY_CONTRACT_VERSION && allowance.purpose === MODULE_ALLOWANCE_PURPOSE,
+    "INVALID_CONTRACT",
+    "Unsupported Module Allowance contract"
+  );
+  assertEconomyIdentifier(allowance.allowanceId, "allowanceId");
+  assertEconomyIdentifier(allowance.householdId, "householdId");
+  assertEconomyIdentifier(allowance.hostWalletId, "hostWalletId");
+  assertEconomyIdentifier(allowance.allowanceWalletId, "allowanceWalletId");
+  assertEconomyIdentifier(allowance.childAccountId, "childAccountId");
+  economyAssert(
+    allowance.hostWalletId !== allowance.allowanceWalletId,
+    "INVALID_CONTRACT",
+    "Host and Module Allowance wallets must be distinct"
+  );
+  economyAssert(
+    allowance.status === "active" || allowance.status === "closed",
+    "INVALID_CONTRACT",
+    "Module Allowance status is unsupported"
+  );
+  const createdAt = parseIsoTimestamp(allowance.createdAt);
+  const updatedAt = parseIsoTimestamp(allowance.updatedAt);
+  economyAssert(
+    updatedAt >= createdAt,
+    "INVALID_TIME_WINDOW",
+    "Module Allowance update cannot precede creation"
+  );
+  economyAssert(
+    Number.isSafeInteger(allowance.version) && allowance.version >= 1,
+    "INVALID_CONTRACT",
+    "Module Allowance version must be a positive safe integer"
+  );
+  const allocated = parseTokenSubunits(allowance.allocatedAmount);
+  const available = parseTokenSubunits(allowance.availableAmount);
+  const held = parseTokenSubunits(allowance.heldAmount);
+  const spent = parseTokenSubunits(allowance.spentAmount);
+  const reclaimed = parseTokenSubunits(allowance.reclaimedAmount);
+  economyAssert(
+    allocated > 0n && [allocated, available, held, spent, reclaimed].every(
+      (amount) => amount >= 0n && isWholeTokenAmount(amount)
+    ),
+    "AMOUNT_NOT_WHOLE_TOKEN",
+    "Module Allowance amounts must be non-negative whole Tokens"
+  );
+  economyAssert(
+    allocated === available + held + spent + reclaimed,
+    "INVALID_CONTRACT",
+    "Module Allowance buckets must equal its lifetime allocation"
+  );
+  economyAssert(
+    allowance.status !== "closed" || available === 0n && held === 0n,
+    "INVALID_CONTRACT",
+    "A closed Module Allowance cannot retain available or held value"
+  );
+  const fundedByLot = sumSlicesByLot(allowance.fundingSlices);
+  const reclaimedByLot = sumSlicesByLot(allowance.reclaimedSlices);
+  economyAssert(
+    sumTokenSubunits(allowance.fundingSlices.map((slice) => slice.amount)) === allocated,
+    "INVALID_CONTRACT",
+    "Module Allowance funding provenance must equal allocated value"
+  );
+  economyAssert(
+    sumTokenSubunits(allowance.reclaimedSlices.map((slice) => slice.amount)) === reclaimed,
+    "INVALID_CONTRACT",
+    "Module Allowance reclaim provenance must equal reclaimed value"
+  );
+  for (const [lotId, amount] of reclaimedByLot) {
+    economyAssert(
+      amount <= (fundedByLot.get(lotId) ?? 0n),
+      "SOURCE_LOT_RESTRICTED",
+      "Reclaimed provenance cannot exceed Module Allowance funding"
+    );
+  }
+}
+function createModuleAllowance(input) {
+  const amount = assertWholePositive2(input.amount, "Module Allowance amount");
+  assertPositiveSlices(input.fundingSlices, amount, "Funding slices");
+  const allowance = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    purpose: MODULE_ALLOWANCE_PURPOSE,
+    allowanceId: input.allowanceId,
+    householdId: input.householdId,
+    hostWalletId: input.hostWalletId,
+    allowanceWalletId: input.allowanceWalletId,
+    childAccountId: input.childAccountId,
+    status: "active",
+    allocatedAmount: input.amount,
+    availableAmount: input.amount,
+    heldAmount: serializeTokenSubunits(0n),
+    spentAmount: serializeTokenSubunits(0n),
+    reclaimedAmount: serializeTokenSubunits(0n),
+    fundingSlices: input.fundingSlices,
+    reclaimedSlices: [],
+    version: 1,
+    createdAt: input.occurredAt,
+    updatedAt: input.occurredAt
+  };
+  assertModuleAllowance(allowance);
+  return allowance;
+}
+function fundModuleAllowance(allowance, input) {
+  assertModuleAllowance(allowance);
+  economyAssert(
+    allowance.status === "active" && allowance.version === input.expectedVersion,
+    "INVALID_CONTRACT",
+    "Module Allowance is closed or its optimistic version is stale"
+  );
+  assertUpdatedAt(allowance.updatedAt, input.occurredAt, "Funding time");
+  const amount = assertWholePositive2(input.amount, "Module Allowance funding");
+  assertPositiveSlices(input.fundingSlices, amount, "Funding slices");
+  const next = {
+    ...allowance,
+    allocatedAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.allocatedAmount) + amount
+    ),
+    availableAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.availableAmount) + amount
+    ),
+    fundingSlices: [...allowance.fundingSlices, ...input.fundingSlices],
+    version: allowance.version + 1,
+    updatedAt: input.occurredAt
+  };
+  assertModuleAllowance(next);
+  return next;
+}
+function reclaimModuleAllowance(allowance, input) {
+  assertModuleAllowance(allowance);
+  economyAssert(
+    allowance.status === "active" && allowance.version === input.expectedVersion,
+    "INVALID_CONTRACT",
+    "Module Allowance is closed or its optimistic version is stale"
+  );
+  assertUpdatedAt(allowance.updatedAt, input.occurredAt, "Reclaim time");
+  const amount = assertWholePositive2(input.amount, "Module Allowance reclaim");
+  economyAssert(
+    amount <= parseTokenSubunits(allowance.availableAmount),
+    "INSUFFICIENT_BALANCE",
+    "Cannot reclaim held, spent, or unavailable Module Allowance value"
+  );
+  assertPositiveSlices(input.sourceSlices, amount, "Reclaim slices");
+  const fundedLotIds = new Set(
+    allowance.fundingSlices.map((slice) => slice.lotId)
+  );
+  economyAssert(
+    input.sourceSlices.every((slice) => fundedLotIds.has(slice.lotId)),
+    "SOURCE_LOT_RESTRICTED",
+    "Reclaim slices must originate from the Module Allowance"
+  );
+  const next = {
+    ...allowance,
+    availableAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.availableAmount) - amount
+    ),
+    reclaimedAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.reclaimedAmount) + amount
+    ),
+    reclaimedSlices: [...allowance.reclaimedSlices, ...input.sourceSlices],
+    version: allowance.version + 1,
+    updatedAt: input.occurredAt
+  };
+  assertModuleAllowance(next);
+  return next;
+}
+function closeModuleAllowance(allowance, input) {
+  assertModuleAllowance(allowance);
+  economyAssert(
+    allowance.status === "active" && allowance.version === input.expectedVersion,
+    "INVALID_CONTRACT",
+    "Module Allowance is closed or its optimistic version is stale"
+  );
+  assertUpdatedAt(allowance.updatedAt, input.occurredAt, "Closure time");
+  economyAssert(
+    parseTokenSubunits(allowance.availableAmount) === 0n && parseTokenSubunits(allowance.heldAmount) === 0n,
+    "INVALID_CONTRACT",
+    "Available value must be reclaimed and holds resolved before closure"
+  );
+  const next = {
+    ...allowance,
+    status: "closed",
+    version: allowance.version + 1,
+    updatedAt: input.occurredAt
+  };
+  assertModuleAllowance(next);
+  return next;
+}
+function assertModuleSpendQuote(quote) {
+  economyAssert(
+    quote.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported module-spend quote contract version"
+  );
+  assertEconomyIdentifier(quote.quoteId, "quoteId");
+  assertEconomyIdentifier(quote.allowanceId, "allowanceId");
+  assertEconomyIdentifier(quote.householdId, "householdId");
+  assertEconomyIdentifier(quote.guardianAccountId, "guardianAccountId");
+  assertEconomyIdentifier(quote.childAccountId, "childAccountId");
+  assertEconomyIdentifier(quote.moduleVersionId, "moduleVersionId");
+  assertEconomyIdentifier(quote.catalogVersion, "catalogVersion");
+  assertEconomyIdentifier(
+    quote.requirementsManifestVersion,
+    "requirementsManifestVersion"
+  );
+  assertSha256Reference(
+    quote.requirementsManifestHash,
+    "Requirements manifest hash"
+  );
+  assertWholePositive2(quote.amount, "Module price");
+  const acknowledgedAt = parseIsoTimestamp(quote.requirementsAcknowledgedAt);
+  const issuedAt = parseIsoTimestamp(quote.issuedAt);
+  const expiresAt = parseIsoTimestamp(quote.expiresAt);
+  economyAssert(
+    acknowledgedAt <= issuedAt && expiresAt > issuedAt,
+    "INVALID_TIME_WINDOW",
+    "Requirements must be acknowledged before a bounded quote is issued"
+  );
+}
+function createModuleSpendQuote(input) {
+  const quote = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    ...input
+  };
+  assertModuleSpendQuote(quote);
+  return quote;
+}
+function assertModuleSpendHold(hold) {
+  economyAssert(
+    hold.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported module-spend hold contract version"
+  );
+  assertEconomyIdentifier(hold.holdId, "holdId");
+  assertEconomyIdentifier(hold.quoteId, "quoteId");
+  assertEconomyIdentifier(hold.allowanceId, "allowanceId");
+  assertEconomyIdentifier(hold.householdId, "householdId");
+  assertEconomyIdentifier(hold.guardianAccountId, "guardianAccountId");
+  assertEconomyIdentifier(hold.childAccountId, "childAccountId");
+  assertEconomyIdentifier(hold.moduleVersionId, "moduleVersionId");
+  assertEconomyIdentifier(
+    hold.requirementsManifestVersion,
+    "requirementsManifestVersion"
+  );
+  assertSha256Reference(
+    hold.requirementsManifestHash,
+    "Requirements manifest hash"
+  );
+  assertEconomyIdentifier(hold.holdIdempotencyKey, "holdIdempotencyKey");
+  const amount = assertWholePositive2(hold.amount, "Module hold amount");
+  assertPositiveSlices(hold.sourceSlices, amount, "Hold source slices");
+  economyAssert(
+    ["held", "settled", "released"].includes(hold.status),
+    "INVALID_CONTRACT",
+    "Module hold status is unsupported"
+  );
+  economyAssert(
+    Number.isSafeInteger(hold.version) && hold.version >= 1,
+    "INVALID_CONTRACT",
+    "Module hold version must be a positive safe integer"
+  );
+  const createdAt = parseIsoTimestamp(hold.createdAt);
+  const expiresAt = parseIsoTimestamp(hold.expiresAt);
+  const updatedAt = parseIsoTimestamp(hold.updatedAt);
+  economyAssert(
+    expiresAt > createdAt && updatedAt >= createdAt,
+    "INVALID_TIME_WINDOW",
+    "Module hold requires a bounded lifetime and ordered updates"
+  );
+  if (hold.status === "held") {
+    economyAssert(
+      hold.entitlementId === void 0 && hold.settlementTransactionId === void 0 && hold.releaseTransactionId === void 0 && hold.settlementIdempotencyKey === void 0 && hold.releaseIdempotencyKey === void 0,
+      "INVALID_CONTRACT",
+      "An unsettled hold cannot claim an entitlement or final transaction"
+    );
+  } else if (hold.status === "settled") {
+    economyAssert(
+      hold.entitlementId !== void 0 && hold.settlementTransactionId !== void 0 && hold.settlementIdempotencyKey !== void 0 && hold.releaseTransactionId === void 0 && hold.releaseIdempotencyKey === void 0,
+      "INVALID_CONTRACT",
+      "A settled hold requires entitlement and transaction evidence"
+    );
+    assertEconomyIdentifier(hold.entitlementId, "entitlementId");
+    assertEconomyIdentifier(
+      hold.settlementTransactionId,
+      "settlementTransactionId"
+    );
+    assertEconomyIdentifier(
+      hold.settlementIdempotencyKey,
+      "settlementIdempotencyKey"
+    );
+  } else {
+    economyAssert(
+      hold.entitlementId === void 0 && hold.settlementTransactionId === void 0 && hold.settlementIdempotencyKey === void 0 && hold.releaseTransactionId !== void 0 && hold.releaseIdempotencyKey !== void 0,
+      "INVALID_CONTRACT",
+      "A released hold requires release evidence only"
+    );
+    assertEconomyIdentifier(hold.releaseTransactionId, "releaseTransactionId");
+    assertEconomyIdentifier(hold.releaseIdempotencyKey, "releaseIdempotencyKey");
+  }
+}
+function assertAllowanceMatchesQuote(allowance, quote) {
+  economyAssert(
+    allowance.status === "active" && allowance.allowanceId === quote.allowanceId && allowance.householdId === quote.householdId && allowance.childAccountId === quote.childAccountId,
+    "INVALID_CONTRACT",
+    "Module quote does not belong to this active child allowance"
+  );
+}
+function assertAllowanceMatchesHold(allowance, hold) {
+  economyAssert(
+    allowance.status === "active" && allowance.allowanceId === hold.allowanceId && allowance.householdId === hold.householdId && allowance.childAccountId === hold.childAccountId,
+    "INVALID_CONTRACT",
+    "Module hold does not belong to this active child allowance"
+  );
+}
+function createModuleSpendHold(allowance, quote, input) {
+  assertModuleAllowance(allowance);
+  assertModuleSpendQuote(quote);
+  assertAllowanceMatchesQuote(allowance, quote);
+  economyAssert(
+    allowance.version === input.expectedAllowanceVersion,
+    "INVALID_CONTRACT",
+    "Module Allowance optimistic version is stale"
+  );
+  const occurredAt = parseIsoTimestamp(input.occurredAt);
+  economyAssert(
+    occurredAt >= parseIsoTimestamp(allowance.updatedAt) && occurredAt >= parseIsoTimestamp(quote.issuedAt) && occurredAt < parseIsoTimestamp(quote.expiresAt),
+    "INVALID_TIME_WINDOW",
+    "Module quote is not valid at hold time"
+  );
+  const amount = parseTokenSubunits(quote.amount);
+  economyAssert(
+    amount <= parseTokenSubunits(allowance.availableAmount),
+    "INSUFFICIENT_BALANCE",
+    "Module Allowance has insufficient available value"
+  );
+  assertEconomyIdentifier(input.holdId, "holdId");
+  assertEconomyIdentifier(input.idempotencyKey, "idempotencyKey");
+  assertPositiveSlices(input.sourceSlices, amount, "Hold source slices");
+  const fundedLotIds = new Set(
+    allowance.fundingSlices.map((slice) => slice.lotId)
+  );
+  economyAssert(
+    input.sourceSlices.every((slice) => fundedLotIds.has(slice.lotId)),
+    "SOURCE_LOT_RESTRICTED",
+    "Hold slices must originate from the Module Allowance"
+  );
+  const nextAllowance = {
+    ...allowance,
+    availableAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.availableAmount) - amount
+    ),
+    heldAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.heldAmount) + amount
+    ),
+    version: allowance.version + 1,
+    updatedAt: input.occurredAt
+  };
+  const hold = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    holdId: input.holdId,
+    quoteId: quote.quoteId,
+    allowanceId: quote.allowanceId,
+    householdId: quote.householdId,
+    guardianAccountId: quote.guardianAccountId,
+    childAccountId: quote.childAccountId,
+    moduleVersionId: quote.moduleVersionId,
+    amount: quote.amount,
+    requirementsManifestVersion: quote.requirementsManifestVersion,
+    requirementsManifestHash: quote.requirementsManifestHash,
+    sourceSlices: input.sourceSlices,
+    status: "held",
+    holdIdempotencyKey: input.idempotencyKey,
+    version: 1,
+    createdAt: input.occurredAt,
+    expiresAt: quote.expiresAt,
+    updatedAt: input.occurredAt
+  };
+  assertModuleAllowance(nextAllowance);
+  assertModuleSpendHold(hold);
+  return { allowance: nextAllowance, hold };
+}
+function settleModuleSpendHold(allowance, hold, input) {
+  assertModuleAllowance(allowance);
+  assertModuleSpendHold(hold);
+  assertAllowanceMatchesHold(allowance, hold);
+  economyAssert(
+    hold.status === "held" && allowance.version === input.expectedAllowanceVersion && hold.version === input.expectedHoldVersion,
+    "INVALID_CONTRACT",
+    "Module hold is final or an optimistic version is stale"
+  );
+  assertEconomyIdentifier(input.entitlementId, "entitlementId");
+  assertEconomyIdentifier(
+    input.settlementTransactionId,
+    "settlementTransactionId"
+  );
+  assertEconomyIdentifier(input.idempotencyKey, "idempotencyKey");
+  const occurredAt = parseIsoTimestamp(input.occurredAt);
+  economyAssert(
+    occurredAt >= parseIsoTimestamp(allowance.updatedAt) && occurredAt >= parseIsoTimestamp(hold.updatedAt) && occurredAt < parseIsoTimestamp(hold.expiresAt),
+    "INVALID_TIME_WINDOW",
+    "Module hold cannot settle outside its valid lifetime"
+  );
+  const amount = parseTokenSubunits(hold.amount);
+  economyAssert(
+    amount <= parseTokenSubunits(allowance.heldAmount),
+    "INSUFFICIENT_BALANCE",
+    "Module Allowance does not contain the quoted held value"
+  );
+  const nextAllowance = {
+    ...allowance,
+    heldAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.heldAmount) - amount
+    ),
+    spentAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.spentAmount) + amount
+    ),
+    version: allowance.version + 1,
+    updatedAt: input.occurredAt
+  };
+  const nextHold = {
+    ...hold,
+    status: "settled",
+    settlementIdempotencyKey: input.idempotencyKey,
+    entitlementId: input.entitlementId,
+    settlementTransactionId: input.settlementTransactionId,
+    version: hold.version + 1,
+    updatedAt: input.occurredAt
+  };
+  assertModuleAllowance(nextAllowance);
+  assertModuleSpendHold(nextHold);
+  return { allowance: nextAllowance, hold: nextHold };
+}
+function releaseModuleSpendHold(allowance, hold, input) {
+  assertModuleAllowance(allowance);
+  assertModuleSpendHold(hold);
+  assertAllowanceMatchesHold(allowance, hold);
+  economyAssert(
+    hold.status === "held" && allowance.version === input.expectedAllowanceVersion && hold.version === input.expectedHoldVersion,
+    "INVALID_CONTRACT",
+    "Module hold is final or an optimistic version is stale"
+  );
+  assertEconomyIdentifier(input.releaseTransactionId, "releaseTransactionId");
+  assertEconomyIdentifier(input.idempotencyKey, "idempotencyKey");
+  const occurredAt = parseIsoTimestamp(input.occurredAt);
+  economyAssert(
+    occurredAt >= parseIsoTimestamp(allowance.updatedAt) && occurredAt >= parseIsoTimestamp(hold.updatedAt),
+    "INVALID_TIME_WINDOW",
+    "Module hold release cannot precede its current state"
+  );
+  const amount = parseTokenSubunits(hold.amount);
+  economyAssert(
+    amount <= parseTokenSubunits(allowance.heldAmount),
+    "INSUFFICIENT_BALANCE",
+    "Module Allowance does not contain the quoted held value"
+  );
+  const nextAllowance = {
+    ...allowance,
+    availableAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.availableAmount) + amount
+    ),
+    heldAmount: serializeTokenSubunits(
+      parseTokenSubunits(allowance.heldAmount) - amount
+    ),
+    version: allowance.version + 1,
+    updatedAt: input.occurredAt
+  };
+  const nextHold = {
+    ...hold,
+    status: "released",
+    releaseIdempotencyKey: input.idempotencyKey,
+    releaseTransactionId: input.releaseTransactionId,
+    version: hold.version + 1,
+    updatedAt: input.occurredAt
+  };
+  assertModuleAllowance(nextAllowance);
+  assertModuleSpendHold(nextHold);
+  return { allowance: nextAllowance, hold: nextHold };
+}
+function assertModulePurchaseReceipt(receipt) {
+  economyAssert(
+    receipt.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported module-purchase receipt contract version"
+  );
+  assertEconomyIdentifier(receipt.receiptId, "receiptId");
+  assertEconomyIdentifier(receipt.quoteId, "quoteId");
+  assertEconomyIdentifier(receipt.holdId, "holdId");
+  assertEconomyIdentifier(receipt.allowanceId, "allowanceId");
+  assertEconomyIdentifier(receipt.householdId, "householdId");
+  assertEconomyIdentifier(receipt.guardianAccountId, "guardianAccountId");
+  assertEconomyIdentifier(receipt.childAccountId, "childAccountId");
+  assertEconomyIdentifier(receipt.moduleVersionId, "moduleVersionId");
+  assertEconomyIdentifier(receipt.entitlementId, "entitlementId");
+  assertEconomyIdentifier(
+    receipt.requirementsManifestVersion,
+    "requirementsManifestVersion"
+  );
+  assertSha256Reference(
+    receipt.requirementsManifestHash,
+    "Requirements manifest hash"
+  );
+  assertEconomyIdentifier(
+    receipt.settlementTransactionId,
+    "settlementTransactionId"
+  );
+  assertWholePositive2(receipt.amount, "Receipt amount");
+  parseIsoTimestamp(receipt.issuedAt);
+}
+function createModulePurchaseReceipt(quote, hold, input) {
+  assertModuleSpendQuote(quote);
+  assertModuleSpendHold(hold);
+  economyAssert(
+    hold.status === "settled" && hold.quoteId === quote.quoteId && hold.allowanceId === quote.allowanceId && hold.householdId === quote.householdId && hold.guardianAccountId === quote.guardianAccountId && hold.childAccountId === quote.childAccountId && hold.moduleVersionId === quote.moduleVersionId && hold.amount === quote.amount && hold.requirementsManifestVersion === quote.requirementsManifestVersion && hold.requirementsManifestHash === quote.requirementsManifestHash,
+    "INVALID_CONTRACT",
+    "Receipt quote and settled hold evidence do not match"
+  );
+  economyAssert(
+    parseIsoTimestamp(input.issuedAt) >= parseIsoTimestamp(hold.updatedAt),
+    "INVALID_TIME_WINDOW",
+    "Receipt cannot precede settlement"
+  );
+  const receipt = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    receiptId: input.receiptId,
+    quoteId: quote.quoteId,
+    holdId: hold.holdId,
+    allowanceId: quote.allowanceId,
+    householdId: quote.householdId,
+    guardianAccountId: quote.guardianAccountId,
+    childAccountId: quote.childAccountId,
+    moduleVersionId: quote.moduleVersionId,
+    entitlementId: hold.entitlementId,
+    amount: quote.amount,
+    requirementsManifestVersion: quote.requirementsManifestVersion,
+    requirementsManifestHash: quote.requirementsManifestHash,
+    settlementTransactionId: hold.settlementTransactionId,
+    issuedAt: input.issuedAt
+  };
+  assertModulePurchaseReceipt(receipt);
+  return receipt;
+}
+function assertModulePurchaseReconciliationObservation(observation) {
+  economyAssert(
+    observation.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported module-purchase reconciliation contract version"
+  );
+  assertEconomyIdentifier(observation.quoteId, "quoteId");
+  assertEconomyIdentifier(observation.holdId, "holdId");
+  assertEconomyIdentifier(observation.childAccountId, "childAccountId");
+  assertEconomyIdentifier(observation.moduleVersionId, "moduleVersionId");
+  economyAssert(
+    ["missing", "held", "settled", "released"].includes(
+      observation.financialState
+    ),
+    "INVALID_CONTRACT",
+    "Reconciliation financial state is unsupported"
+  );
+  economyAssert(
+    ["missing", "pending", "active", "cancelled"].includes(
+      observation.entitlementState
+    ),
+    "INVALID_CONTRACT",
+    "Reconciliation entitlement state is unsupported"
+  );
+  economyAssert(
+    typeof observation.receiptPresent === "boolean",
+    "INVALID_CONTRACT",
+    "Receipt presence must be Boolean"
+  );
+  parseIsoTimestamp(observation.observedAt);
+}
+function reconciliationResult(action, reasonCode, blocking = false, consistent = false) {
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    action,
+    blocking,
+    consistent,
+    reasonCode
+  };
+}
+function reconcileModulePurchase(observation) {
+  assertModulePurchaseReconciliationObservation(observation);
+  const { financialState, entitlementState, receiptPresent } = observation;
+  if (receiptPresent && !(financialState === "settled" && entitlementState === "active")) {
+    return reconciliationResult(
+      "manual-review",
+      "receipt-conflicts-with-authoritative-state",
+      true
+    );
+  }
+  if (financialState === "settled" && entitlementState === "active") {
+    return receiptPresent ? reconciliationResult("none", "purchase-consistent", false, true) : reconciliationResult("issue-receipt", "settled-active-receipt-missing");
+  }
+  if (financialState === "held" && entitlementState === "pending") {
+    return reconciliationResult("resume-settlement", "held-pending");
+  }
+  if (financialState === "held" && (entitlementState === "missing" || entitlementState === "cancelled")) {
+    return reconciliationResult("release-hold", "held-without-usable-entitlement");
+  }
+  if (financialState === "settled" && entitlementState === "pending") {
+    return reconciliationResult("activate-entitlement", "settled-pending");
+  }
+  if ((financialState === "missing" || financialState === "released") && entitlementState === "pending") {
+    return reconciliationResult(
+      "cancel-pending-entitlement",
+      "pending-without-settlement-path"
+    );
+  }
+  if ((financialState === "missing" || financialState === "released") && (entitlementState === "missing" || entitlementState === "cancelled")) {
+    return reconciliationResult("none", "no-active-purchase", false, true);
+  }
+  return reconciliationResult(
+    "manual-review",
+    financialState === "settled" ? "settled-debit-without-entitlement" : "active-entitlement-without-settled-debit",
+    true
+  );
+}
+
 // src/operations.ts
 function assertDistinctAdjustmentApproval(request) {
   economyAssert(
@@ -4235,6 +4927,7 @@ function assertSpendRequest(request) {
   EARLY_BACKER_SETTLEMENT_POLICY_V2,
   ECONOMY_CONTRACT_VERSION,
   EconomyError,
+  MODULE_ALLOWANCE_PURPOSE,
   PRE_UTILITY_BACKER_COHORT,
   TOKEN_SUBUNITS_MAX,
   TOKEN_SUBUNITS_MIN,
@@ -4259,6 +4952,11 @@ function assertSpendRequest(request) {
   assertFxSnapshot,
   assertGameplayAllocation,
   assertJournalChainHead,
+  assertModuleAllowance,
+  assertModulePurchaseReceipt,
+  assertModulePurchaseReconciliationObservation,
+  assertModuleSpendHold,
+  assertModuleSpendQuote,
   assertNonNegativeAccounts,
   assertOpenPurchaseIntent,
   assertPaidLotLifecycle,
@@ -4302,10 +5000,15 @@ function assertSpendRequest(request) {
   calculateRollingPurchaseCapUsage,
   canUseSourceLot,
   canonicalTransactionPayload,
+  closeModuleAllowance,
   convertRewardPayout,
   createEarlyBackerRetentionFromPaidLot,
   createGameplayAllocation,
   createInitialSourceLotSnapshot,
+  createModuleAllowance,
+  createModulePurchaseReceipt,
+  createModuleSpendHold,
+  createModuleSpendQuote,
   createPaidLotLifecycle,
   createProjectionSnapshot,
   createPurchaseIntentLifecycle,
@@ -4319,6 +5022,7 @@ function assertSpendRequest(request) {
   economyAssert,
   evaluateEarlyBacker,
   evaluateEarlyBackerBySettlementV2,
+  fundModuleAllowance,
   isWholeTokenAmount,
   mapBitLabsConversionState,
   parseGbpMinorUnits,
@@ -4326,12 +5030,16 @@ function assertSpendRequest(request) {
   parseTokenSubunits,
   rebuildBalanceProjection,
   reclaimGameplayAllocation,
+  reclaimModuleAllowance,
+  reconcileModulePurchase,
   reducePaidLotLifecycleEvents,
   reducePurchaseIntentTransitions,
+  releaseModuleSpendHold,
   reserveRollingPurchaseCaps,
   selectSourceLots,
   serializeGbpMinorUnits,
   serializeTokenSubunits,
+  settleModuleSpendHold,
   sortStringRecord,
   subunitsToWholeTokens,
   sumTokenSubunits,