@plasius/economy 0.1.0

package/dist/index.js

@@ -0,0 +1,1628 @@
+// src/errors.ts
+var EconomyError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "EconomyError";
+    this.code = code;
+  }
+};
+function economyAssert(condition, code, message) {
+  if (!condition) {
+    throw new EconomyError(code, message);
+  }
+}
+function toEconomyErrorEnvelope(error, requestId) {
+  return {
+    schemaVersion: "1",
+    error: {
+      code: error.code,
+      message: error.message.slice(0, 256),
+      ...requestId === void 0 ? {} : { requestId }
+    }
+  };
+}
+
+// src/amount.ts
+var TOKEN_SUBUNITS_PER_TOKEN = 1000n;
+var TOKEN_SUBUNITS_MIN = -(2n ** 63n);
+var TOKEN_SUBUNITS_MAX = 2n ** 63n - 1n;
+var CANONICAL_INTEGER = /^(?:0|-?[1-9][0-9]*)$/u;
+function assertInRange(amount) {
+  economyAssert(
+    amount >= TOKEN_SUBUNITS_MIN && amount <= TOKEN_SUBUNITS_MAX,
+    "AMOUNT_OUT_OF_RANGE",
+    "TokenSubunit amount is outside the signed 64-bit range"
+  );
+}
+function parseTokenSubunits(value) {
+  economyAssert(
+    CANONICAL_INTEGER.test(value),
+    "INVALID_AMOUNT",
+    "TokenSubunit amount must be a canonical base-10 integer string"
+  );
+  try {
+    const amount = BigInt(value);
+    assertInRange(amount);
+    return amount;
+  } catch (error) {
+    if (error instanceof EconomyError) {
+      throw error;
+    }
+    throw new EconomyError("INVALID_AMOUNT", "TokenSubunit amount is invalid");
+  }
+}
+function serializeTokenSubunits(amount) {
+  assertInRange(amount);
+  return amount.toString(10);
+}
+function wholeTokensToSubunits(tokens) {
+  const amount = tokens * TOKEN_SUBUNITS_PER_TOKEN;
+  assertInRange(amount);
+  return amount;
+}
+function isWholeTokenAmount(amount) {
+  return amount % TOKEN_SUBUNITS_PER_TOKEN === 0n;
+}
+function subunitsToWholeTokens(amount) {
+  economyAssert(
+    isWholeTokenAmount(amount),
+    "AMOUNT_NOT_WHOLE_TOKEN",
+    "Amount must contain whole Tokens"
+  );
+  return amount / TOKEN_SUBUNITS_PER_TOKEN;
+}
+function sumTokenSubunits(values) {
+  let total = 0n;
+  for (const value of values) {
+    total += parseTokenSubunits(value);
+    assertInRange(total);
+  }
+  return total;
+}
+
+// src/contracts.ts
+var ECONOMY_CONTRACT_VERSION = "1";
+var IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+function assertEconomyIdentifier(value, label = "identifier") {
+  economyAssert(
+    IDENTIFIER.test(value),
+    "INVALID_CONTRACT",
+    `${label} must be a non-empty opaque identifier`
+  );
+}
+function parseIsoTimestamp(value) {
+  const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{3}))?Z$/u.exec(
+    value
+  );
+  economyAssert(
+    match !== null,
+    "INVALID_CONTRACT",
+    "Timestamp must be an ISO-8601 UTC value"
+  );
+  const milliseconds = Date.parse(value);
+  const base = match[1];
+  const fraction = match[2] ?? "000";
+  economyAssert(
+    Number.isFinite(milliseconds) && base !== void 0 && new Date(milliseconds).toISOString() === `${base}.${fraction}Z`,
+    "INVALID_CONTRACT",
+    "Timestamp must be valid"
+  );
+  return milliseconds;
+}
+function sortStringRecord(value) {
+  return Object.fromEntries(
+    Object.entries(value).sort(([left], [right]) => left.localeCompare(right))
+  );
+}
+
+// src/acquisition.ts
+var BASELINE_GBP_REFERENCE_RATE = Object.freeze({
+  schemaVersion: ECONOMY_CONTRACT_VERSION,
+  rateVersion: "gbp-reference-v1",
+  currency: "GBP",
+  referenceMinorUnitsPerToken: "10",
+  tokenSubunitsPerToken: TOKEN_SUBUNITS_PER_TOKEN.toString(10),
+  cashRedemptionAllowed: false
+});
+var BASELINE_GBP_CATALOG_VERSION = "gbp-v1";
+var BASELINE_GBP_TOKEN_PACKS = Object.freeze([
+  Object.freeze({
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    packId: "gbp_5_50_v1",
+    catalogVersion: BASELINE_GBP_CATALOG_VERSION,
+    currency: "GBP",
+    priceMinorUnits: "500",
+    grantAmount: serializeTokenSubunits(50000n),
+    active: true
+  }),
+  Object.freeze({
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    packId: "gbp_10_100_v1",
+    catalogVersion: BASELINE_GBP_CATALOG_VERSION,
+    currency: "GBP",
+    priceMinorUnits: "1000",
+    grantAmount: serializeTokenSubunits(100000n),
+    active: true
+  }),
+  Object.freeze({
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    packId: "gbp_25_250_v1",
+    catalogVersion: BASELINE_GBP_CATALOG_VERSION,
+    currency: "GBP",
+    priceMinorUnits: "2500",
+    grantAmount: serializeTokenSubunits(250000n),
+    active: true
+  }),
+  Object.freeze({
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    packId: "gbp_50_500_v1",
+    catalogVersion: BASELINE_GBP_CATALOG_VERSION,
+    currency: "GBP",
+    priceMinorUnits: "5000",
+    grantAmount: serializeTokenSubunits(500000n),
+    active: true
+  })
+]);
+var BASELINE_PURCHASE_LIMIT_POLICY = Object.freeze({
+  schemaVersion: ECONOMY_CONTRACT_VERSION,
+  maxOrderPriceMinorUnits: "5000",
+  rollingPayerPriceMinorUnits: "10000",
+  rollingHouseholdPriceMinorUnits: "10000",
+  rollingDays: 30
+});
+function assertRewardConversion(conversion) {
+  economyAssert(
+    conversion.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported reward-conversion contract version"
+  );
+  economyAssert(
+    conversion.provider === "ayet" || conversion.provider === "bitlabs",
+    "INVALID_CONTRACT",
+    "Unsupported reward-conversion provider"
+  );
+  assertEconomyIdentifier(conversion.providerEventId, "providerEventId");
+  assertEconomyIdentifier(
+    conversion.beneficiaryAccountId,
+    "beneficiaryAccountId"
+  );
+  assertEconomyIdentifier(conversion.walletId, "walletId");
+  economyAssert(
+    ["pending", "completed", "reconciled"].includes(conversion.status),
+    "INVALID_CONTRACT",
+    "Unsupported reward-conversion status"
+  );
+  economyAssert(
+    /^[A-Z]{3}$/u.test(conversion.providerCurrency),
+    "INVALID_CONTRACT",
+    "Reward payout currency must use an uppercase ISO code"
+  );
+  economyAssert(
+    parseNonNegativeInteger(
+      conversion.providerPayoutMinorUnits,
+      "Provider payout"
+    ) > 0n && parseNonNegativeInteger(conversion.gbpMinorUnits, "GBP payout") >= 0n && parseTokenSubunits(conversion.tokenSubunits) > 0n,
+    "INVALID_AMOUNT",
+    "Reward conversion must carry positive payout and Token values"
+  );
+  assertEconomyIdentifier(conversion.rateVersion, "rateVersion");
+  assertEconomyIdentifier(conversion.fxSnapshotId, "fxSnapshotId");
+  parseIsoTimestamp(conversion.occurredAt);
+}
+function parseNonNegativeInteger(value, label) {
+  economyAssert(
+    /^(?:0|[1-9][0-9]*)$/u.test(value),
+    "INVALID_AMOUNT",
+    `${label} must be a non-negative integer string`
+  );
+  return BigInt(value);
+}
+function assertTokenPack(pack) {
+  economyAssert(
+    pack.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported Token pack contract version"
+  );
+  assertEconomyIdentifier(pack.packId, "packId");
+  assertEconomyIdentifier(pack.catalogVersion, "catalogVersion");
+  economyAssert(
+    pack.currency === "GBP" && typeof pack.active === "boolean",
+    "INVALID_CONTRACT",
+    "Token packs must use GBP and declare whether they are active"
+  );
+  economyAssert(
+    parseNonNegativeInteger(pack.priceMinorUnits, "Pack price") > 0n,
+    "INVALID_AMOUNT",
+    "Pack price must be positive"
+  );
+  const grant = parseTokenSubunits(pack.grantAmount);
+  economyAssert(
+    grant > 0n && isWholeTokenAmount(grant),
+    "AMOUNT_NOT_WHOLE_TOKEN",
+    "Paid pack grants must contain whole Tokens"
+  );
+}
+function assertTokenReferenceRate(rate) {
+  economyAssert(
+    rate.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported Token reference-rate contract version"
+  );
+  assertEconomyIdentifier(rate.rateVersion, "rateVersion");
+  const referenceMinorUnits = parseNonNegativeInteger(
+    rate.referenceMinorUnitsPerToken,
+    "Reference minor units per Token"
+  );
+  const subunitsPerToken = parseNonNegativeInteger(
+    rate.tokenSubunitsPerToken,
+    "TokenSubunits per Token"
+  );
+  economyAssert(
+    rate.currency === "GBP" && referenceMinorUnits > 0n && subunitsPerToken === TOKEN_SUBUNITS_PER_TOKEN && rate.cashRedemptionAllowed === false,
+    "INVALID_CONTRACT",
+    "Token reference rate must preserve the GBP nominal, subunit, and no-redemption boundary"
+  );
+}
+function assertFlatTokenCatalog(packs, referenceRate) {
+  assertTokenReferenceRate(referenceRate);
+  economyAssert(
+    packs.length > 0,
+    "INVALID_CONTRACT",
+    "Token catalog must contain at least one pack"
+  );
+  const packIds = /* @__PURE__ */ new Set();
+  const catalogVersion = packs[0]?.catalogVersion;
+  const referenceMinorUnits = BigInt(
+    referenceRate.referenceMinorUnitsPerToken
+  );
+  const subunitsPerToken = BigInt(referenceRate.tokenSubunitsPerToken);
+  for (const pack of packs) {
+    assertTokenPack(pack);
+    economyAssert(
+      !packIds.has(pack.packId),
+      "DUPLICATE_IDENTIFIER",
+      "Token catalog pack IDs must be unique"
+    );
+    economyAssert(
+      pack.catalogVersion === catalogVersion,
+      "INVALID_CONTRACT",
+      "Token catalog packs must share one catalog version"
+    );
+    packIds.add(pack.packId);
+    const scaledReference = parseTokenSubunits(pack.grantAmount) * referenceMinorUnits;
+    economyAssert(
+      scaledReference % subunitsPerToken === 0n && scaledReference / subunitsPerToken === BigInt(pack.priceMinorUnits),
+      "INVALID_CONTRACT",
+      "Token catalog must use the declared flat nominal reference ratio"
+    );
+  }
+}
+function assertPurchaseLimitPolicy(policy) {
+  economyAssert(
+    policy.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported purchase-limit contract version"
+  );
+  const maxOrder = parseNonNegativeInteger(
+    policy.maxOrderPriceMinorUnits,
+    "Maximum order"
+  );
+  const payer = parseNonNegativeInteger(
+    policy.rollingPayerPriceMinorUnits,
+    "Rolling payer limit"
+  );
+  const household = parseNonNegativeInteger(
+    policy.rollingHouseholdPriceMinorUnits,
+    "Rolling household limit"
+  );
+  economyAssert(
+    maxOrder > 0n && payer >= maxOrder && household >= maxOrder,
+    "INVALID_AMOUNT",
+    "Rolling purchase limits must cover at least one maximum order"
+  );
+  economyAssert(
+    Number.isSafeInteger(policy.rollingDays) && policy.rollingDays >= 1 && policy.rollingDays <= 365,
+    "INVALID_CONTRACT",
+    "Purchase-limit rolling window must be a bounded whole-day count"
+  );
+}
+function assertPurchaseIntentBinding(intent, pack) {
+  assertTokenPack(pack);
+  economyAssert(
+    intent.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported purchase-intent contract version"
+  );
+  assertEconomyIdentifier(intent.intentId, "intentId");
+  assertEconomyIdentifier(intent.payerAccountId, "payerAccountId");
+  assertEconomyIdentifier(intent.receivingHouseholdId, "receivingHouseholdId");
+  assertEconomyIdentifier(intent.receivingWalletId, "receivingWalletId");
+  assertEconomyIdentifier(intent.packId, "packId");
+  assertEconomyIdentifier(intent.catalogVersion, "catalogVersion");
+  const createdAt = parseIsoTimestamp(intent.createdAt);
+  const expiresAt = parseIsoTimestamp(intent.expiresAt);
+  economyAssert(
+    expiresAt > createdAt,
+    "INVALID_TIME_WINDOW",
+    "Purchase intent expiry must follow its creation time"
+  );
+  economyAssert(
+    intent.expectedCurrency === "GBP" && intent.packId === pack.packId && intent.catalogVersion === pack.catalogVersion && intent.expectedCurrency === pack.currency && intent.expectedPriceMinorUnits === pack.priceMinorUnits && intent.grantAmount === pack.grantAmount,
+    "INVALID_CONTRACT",
+    "Purchase intent does not match its authoritative catalog pack"
+  );
+  parseNonNegativeInteger(intent.expectedPriceMinorUnits, "Expected price");
+  parseTokenSubunits(intent.grantAmount);
+  economyAssert(
+    [
+      "created",
+      "checkout-created",
+      "paid-unreconciled",
+      "credited",
+      "expired",
+      "cancelled",
+      "disputed"
+    ].includes(intent.status),
+    "INVALID_CONTRACT",
+    "Purchase intent has an unsupported status"
+  );
+  if (intent.providerCheckoutReferenceHash !== void 0) {
+    economyAssert(
+      /^sha256:[a-f0-9]{64}$/u.test(intent.providerCheckoutReferenceHash),
+      "INVALID_CONTRACT",
+      "Checkout references must be stored as sanitized SHA-256 hashes"
+    );
+  }
+}
+function assertOpenPurchaseIntent(intent, pack, checkedAt) {
+  assertPurchaseIntentBinding(intent, pack);
+  const checkedAtValue = parseIsoTimestamp(checkedAt);
+  economyAssert(
+    pack.active && (intent.status === "created" || intent.status === "checkout-created") && checkedAtValue >= parseIsoTimestamp(intent.createdAt) && checkedAtValue < parseIsoTimestamp(intent.expiresAt),
+    "INVALID_TIME_WINDOW",
+    "Purchase intent is inactive, expired, or not open for checkout"
+  );
+}
+function assertRewardRate(rate) {
+  economyAssert(
+    rate.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported reward-rate contract version"
+  );
+  assertEconomyIdentifier(rate.rateVersion, "rateVersion");
+  economyAssert(
+    rate.provider === "ayet" || rate.provider === "bitlabs",
+    "INVALID_CONTRACT",
+    "Unsupported reward provider"
+  );
+  const effectiveFrom = parseIsoTimestamp(rate.effectiveFrom);
+  if (rate.effectiveUntil !== void 0) {
+    economyAssert(
+      parseIsoTimestamp(rate.effectiveUntil) > effectiveFrom,
+      "INVALID_TIME_WINDOW",
+      "Reward-rate expiry must follow its effective time"
+    );
+  }
+}
+function assertFxSnapshot(fx) {
+  economyAssert(
+    fx.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported FX snapshot contract version"
+  );
+  assertEconomyIdentifier(fx.snapshotId, "snapshotId");
+  economyAssert(
+    /^[A-Z]{3}$/u.test(fx.sourceCurrency) && fx.quoteCurrency === "GBP",
+    "INVALID_CONTRACT",
+    "FX snapshots must convert an ISO currency into GBP"
+  );
+  parseIsoTimestamp(fx.capturedAt);
+}
+function convertRewardPayout(providerPayoutMinorUnits, rate, fx) {
+  assertRewardRate(rate);
+  assertFxSnapshot(fx);
+  const payout = parseNonNegativeInteger(
+    providerPayoutMinorUnits,
+    "Provider payout"
+  );
+  const fxNumerator = parseNonNegativeInteger(
+    fx.gbpMinorUnitsNumerator,
+    "FX numerator"
+  );
+  const fxDenominator = parseNonNegativeInteger(
+    fx.sourceMinorUnitsDenominator,
+    "FX denominator"
+  );
+  const tokenNumerator = parseNonNegativeInteger(
+    rate.tokenSubunitsNumerator,
+    "Rate numerator"
+  );
+  const tokenDenominator = parseNonNegativeInteger(
+    rate.gbpMinorUnitsDenominator,
+    "Rate denominator"
+  );
+  economyAssert(
+    fxDenominator > 0n && tokenDenominator > 0n,
+    "INVALID_AMOUNT",
+    "FX and reward-rate denominators must be positive"
+  );
+  economyAssert(
+    fxNumerator > 0n && tokenNumerator > 0n,
+    "INVALID_AMOUNT",
+    "FX and reward-rate numerators must be positive"
+  );
+  const gbpMinorUnits = payout * fxNumerator / fxDenominator;
+  const tokenSubunits = gbpMinorUnits * tokenNumerator / tokenDenominator;
+  return {
+    gbpMinorUnits: gbpMinorUnits.toString(10),
+    tokenSubunits: serializeTokenSubunits(tokenSubunits)
+  };
+}
+function mapBitLabsConversionState(state) {
+  const transitions = {
+    PENDING: {
+      conversionStatus: "pending",
+      activityType: "hold",
+      activityStatus: "held"
+    },
+    COMPLETED: {
+      conversionStatus: "completed",
+      activityType: "offerwall",
+      activityStatus: "settled"
+    },
+    RECONCILED: {
+      conversionStatus: "reconciled",
+      activityType: "reversal",
+      activityStatus: "reversed"
+    }
+  };
+  const transition = transitions[state];
+  economyAssert(
+    transition !== void 0,
+    "INVALID_CONTRACT",
+    "Unsupported BitLabs conversion state"
+  );
+  return transition;
+}
+
+// src/allocations.ts
+function assertWholePositive(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 assertSlices(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 command amount`
+  );
+}
+function assertGameplayAllocation(allocation) {
+  economyAssert(
+    allocation.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported allocation contract version"
+  );
+  assertEconomyIdentifier(allocation.allocationId, "allocationId");
+  assertEconomyIdentifier(allocation.householdId, "householdId");
+  assertEconomyIdentifier(allocation.hostWalletId, "hostWalletId");
+  assertEconomyIdentifier(allocation.childWalletId, "childWalletId");
+  assertEconomyIdentifier(allocation.childAccountId, "childAccountId");
+  const createdAt = parseIsoTimestamp(allocation.createdAt);
+  const updatedAt = parseIsoTimestamp(allocation.updatedAt);
+  economyAssert(
+    updatedAt >= createdAt,
+    "INVALID_TIME_WINDOW",
+    "Allocation update time cannot precede its creation time"
+  );
+  economyAssert(
+    allocation.status === "active" || allocation.status === "closed",
+    "INVALID_CONTRACT",
+    "Allocation has an unsupported status"
+  );
+  const reserved = parseTokenSubunits(allocation.reservedAmount);
+  const remaining = parseTokenSubunits(allocation.remainingAmount);
+  const reclaimed = parseTokenSubunits(allocation.reclaimedAmount);
+  economyAssert(
+    reserved > 0n && remaining >= 0n && reclaimed >= 0n && isWholeTokenAmount(reserved) && isWholeTokenAmount(remaining) && isWholeTokenAmount(reclaimed),
+    "AMOUNT_NOT_WHOLE_TOKEN",
+    "Allocation reservations and reclaims must contain whole Tokens"
+  );
+  economyAssert(
+    remaining + reclaimed <= reserved,
+    "INVALID_CONTRACT",
+    "Allocation remaining and reclaimed amounts exceed its reservation"
+  );
+  const fundingByLot = /* @__PURE__ */ new Map();
+  let funded = 0n;
+  for (const slice of allocation.fundingSlices) {
+    assertEconomyIdentifier(slice.lotId, "lotId");
+    const amount = parseTokenSubunits(slice.amount);
+    economyAssert(
+      amount > 0n,
+      "INVALID_AMOUNT",
+      "Allocation funding slices must be positive"
+    );
+    funded += amount;
+    fundingByLot.set(
+      slice.lotId,
+      (fundingByLot.get(slice.lotId) ?? 0n) + amount
+    );
+  }
+  economyAssert(
+    funded === reserved,
+    "INVALID_CONTRACT",
+    "Allocation funding provenance must equal its total reservation"
+  );
+  const reclaimedByLot = /* @__PURE__ */ new Map();
+  let reclaimedFromSlices = 0n;
+  for (const slice of allocation.reclaimedSlices) {
+    assertEconomyIdentifier(slice.lotId, "lotId");
+    const amount = parseTokenSubunits(slice.amount);
+    economyAssert(
+      amount > 0n,
+      "INVALID_AMOUNT",
+      "Allocation reclaim slices must be positive"
+    );
+    reclaimedFromSlices += amount;
+    reclaimedByLot.set(
+      slice.lotId,
+      (reclaimedByLot.get(slice.lotId) ?? 0n) + amount
+    );
+  }
+  economyAssert(
+    reclaimedFromSlices === reclaimed,
+    "INVALID_CONTRACT",
+    "Allocation reclaim provenance must equal its reclaimed amount"
+  );
+  for (const [lotId, amount] of reclaimedByLot) {
+    economyAssert(
+      amount <= (fundingByLot.get(lotId) ?? 0n),
+      "SOURCE_LOT_RESTRICTED",
+      "Reclaimed provenance cannot exceed allocation funding"
+    );
+  }
+  economyAssert(
+    allocation.version >= 1 && Number.isSafeInteger(allocation.version),
+    "INVALID_CONTRACT",
+    "Allocation version must be a positive safe integer"
+  );
+  const perTransaction = parseTokenSubunits(allocation.limits.perTransaction);
+  const periodic = parseTokenSubunits(allocation.limits.periodic);
+  economyAssert(
+    ["daily", "weekly", "monthly"].includes(allocation.limits.periodicWindow),
+    "INVALID_CONTRACT",
+    "Gameplay limit has an unsupported period"
+  );
+  economyAssert(
+    perTransaction >= 0n && periodic >= 0n && isWholeTokenAmount(perTransaction) && isWholeTokenAmount(periodic),
+    "AMOUNT_NOT_WHOLE_TOKEN",
+    "Gameplay limits must contain whole Tokens"
+  );
+  economyAssert(
+    perTransaction <= periodic || periodic === 0n,
+    "INVALID_CONTRACT",
+    "Per-transaction limit cannot exceed an enabled periodic limit"
+  );
+}
+function createGameplayAllocation(input) {
+  const amount = assertWholePositive(input.amount, "Allocation amount");
+  assertSlices(input.fundingSlices, amount, "Allocation funding slices");
+  const allocation = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    allocationId: input.allocationId,
+    householdId: input.householdId,
+    hostWalletId: input.hostWalletId,
+    childWalletId: input.childWalletId,
+    childAccountId: input.childAccountId,
+    status: "active",
+    reservedAmount: input.amount,
+    remainingAmount: input.amount,
+    reclaimedAmount: serializeTokenSubunits(0n),
+    fundingSlices: input.fundingSlices,
+    reclaimedSlices: [],
+    limits: input.limits,
+    version: 1,
+    createdAt: input.occurredAt,
+    updatedAt: input.occurredAt
+  };
+  assertGameplayAllocation(allocation);
+  return allocation;
+}
+function boostGameplayAllocation(allocation, input) {
+  assertGameplayAllocation(allocation);
+  economyAssert(
+    allocation.status === "active" && allocation.version === input.expectedVersion,
+    "INVALID_CONTRACT",
+    "Allocation is closed or its optimistic version is stale"
+  );
+  const amount = assertWholePositive(input.amount, "Boost amount");
+  assertSlices(input.fundingSlices, amount, "Boost funding slices");
+  const next = {
+    ...allocation,
+    reservedAmount: serializeTokenSubunits(
+      parseTokenSubunits(allocation.reservedAmount) + amount
+    ),
+    remainingAmount: serializeTokenSubunits(
+      parseTokenSubunits(allocation.remainingAmount) + amount
+    ),
+    fundingSlices: [...allocation.fundingSlices, ...input.fundingSlices],
+    version: allocation.version + 1,
+    updatedAt: input.occurredAt
+  };
+  assertGameplayAllocation(next);
+  return next;
+}
+function reclaimGameplayAllocation(allocation, input) {
+  assertGameplayAllocation(allocation);
+  economyAssert(
+    allocation.status === "active" && allocation.version === input.expectedVersion,
+    "INVALID_CONTRACT",
+    "Allocation is closed or its optimistic version is stale"
+  );
+  const amount = assertWholePositive(input.amount, "Reclaim amount");
+  economyAssert(
+    amount <= parseTokenSubunits(allocation.remainingAmount),
+    "INSUFFICIENT_BALANCE",
+    "Cannot reclaim more than the unused allocation"
+  );
+  assertSlices(input.sourceSlices, amount, "Reclaim source slices");
+  const fundedLotIds = new Set(
+    allocation.fundingSlices.map((slice) => slice.lotId)
+  );
+  economyAssert(
+    input.sourceSlices.every((slice) => fundedLotIds.has(slice.lotId)),
+    "SOURCE_LOT_RESTRICTED",
+    "Reclaim slices must originate from the allocation"
+  );
+  const remaining = parseTokenSubunits(allocation.remainingAmount) - amount;
+  const next = {
+    ...allocation,
+    remainingAmount: serializeTokenSubunits(remaining),
+    reclaimedAmount: serializeTokenSubunits(
+      parseTokenSubunits(allocation.reclaimedAmount) + amount
+    ),
+    reclaimedSlices: [...allocation.reclaimedSlices, ...input.sourceSlices],
+    status: remaining === 0n ? "closed" : allocation.status,
+    version: allocation.version + 1,
+    updatedAt: input.occurredAt
+  };
+  assertGameplayAllocation(next);
+  return next;
+}
+
+// src/early-backers.ts
+var PRE_UTILITY_BACKER_COHORT = "pre_utility_backer_v1";
+function isWithinWindow(timestamp, launch, cutoff) {
+  const value = parseIsoTimestamp(timestamp);
+  return value >= launch && (cutoff === void 0 || value < cutoff);
+}
+function evaluateEarlyBacker(payerAccountId, receivingHouseholdId, paidLots, window, evaluatedAt) {
+  assertEconomyIdentifier(payerAccountId, "payerAccountId");
+  assertEconomyIdentifier(receivingHouseholdId, "receivingHouseholdId");
+  const launch = parseIsoTimestamp(window.publicTokensLaunchAt);
+  const cutoff = window.firstPublicSpendLiveAt === void 0 ? void 0 : parseIsoTimestamp(window.firstPublicSpendLiveAt);
+  economyAssert(
+    cutoff === void 0 || cutoff > launch,
+    "INVALID_TIME_WINDOW",
+    "First public spend must occur after public Token launch"
+  );
+  parseIsoTimestamp(evaluatedAt);
+  let retained = 0n;
+  const contributingLotIds = [];
+  const seenLotIds = /* @__PURE__ */ new Set();
+  for (const lot of paidLots) {
+    economyAssert(
+      lot.schemaVersion === ECONOMY_CONTRACT_VERSION,
+      "INVALID_CONTRACT",
+      "Unsupported paid-lot retention contract version"
+    );
+    assertEconomyIdentifier(lot.lotId, "lotId");
+    economyAssert(
+      !seenLotIds.has(lot.lotId),
+      "DUPLICATE_IDENTIFIER",
+      "Paid-lot retention input must not repeat a source lot"
+    );
+    seenLotIds.add(lot.lotId);
+    assertEconomyIdentifier(lot.payerAccountId, "payerAccountId");
+    assertEconomyIdentifier(lot.receivingHouseholdId, "receivingHouseholdId");
+    assertEconomyIdentifier(lot.purchaseId, "purchaseId");
+    assertEconomyIdentifier(lot.catalogVersion, "catalogVersion");
+    const purchasedAt = parseIsoTimestamp(lot.purchasedAt);
+    const settledAt = parseIsoTimestamp(lot.settledAt);
+    const creditedAt = parseIsoTimestamp(lot.creditedAt);
+    economyAssert(
+      purchasedAt <= settledAt && settledAt <= creditedAt,
+      "INVALID_TIME_WINDOW",
+      "Paid-lot timestamps must follow purchase, settlement, then credit order"
+    );
+    if (lot.payerAccountId !== payerAccountId || lot.receivingHouseholdId !== receivingHouseholdId) {
+      continue;
+    }
+    const inWindow = isWithinWindow(lot.purchasedAt, launch, cutoff) && isWithinWindow(lot.settledAt, launch, cutoff) && isWithinWindow(lot.creditedAt, launch, cutoff);
+    const amount = parseTokenSubunits(lot.retainedAmount);
+    economyAssert(
+      amount >= 0n,
+      "INVALID_AMOUNT",
+      "Retained paid-lot basis cannot be negative"
+    );
+    if (inWindow && amount > 0n) {
+      retained += amount;
+      contributingLotIds.push(lot.lotId);
+    }
+  }
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    cohortKey: PRE_UTILITY_BACKER_COHORT,
+    status: retained > 0n ? "provisional" : "not-qualified",
+    payerAccountId,
+    receivingHouseholdId,
+    netRetainedAmount: serializeTokenSubunits(retained),
+    contributingLotIds: contributingLotIds.sort(
+      (left, right) => left.localeCompare(right)
+    ),
+    evaluatedAt
+  };
+}
+
+// src/ledger.ts
+var ACTIVITY_TYPES = /* @__PURE__ */ new Set([
+  "purchase",
+  "subscription",
+  "rewarded-ad",
+  "offerwall",
+  "allocation",
+  "boost",
+  "reclaim",
+  "spend",
+  "hold",
+  "refund",
+  "chargeback",
+  "adjustment",
+  "reversal",
+  "event",
+  "competition"
+]);
+var ACTIVITY_STATUSES = /* @__PURE__ */ new Set([
+  "pending",
+  "held",
+  "settled",
+  "reversed",
+  "failed"
+]);
+function assertCanonicalHash(value, label) {
+  economyAssert(
+    /^sha256:[a-f0-9]{64}$/u.test(value),
+    "INVALID_CONTRACT",
+    `${label} must be a canonical SHA-256 reference`
+  );
+}
+function hasControlCharacters(value) {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31 || code === 127;
+  });
+}
+function assertActivityEntry(entry) {
+  economyAssert(
+    entry.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported activity-entry contract version"
+  );
+  assertEconomyIdentifier(entry.transactionId, "transactionId");
+  economyAssert(
+    ACTIVITY_TYPES.has(entry.activityType) && ACTIVITY_STATUSES.has(entry.status),
+    "INVALID_CONTRACT",
+    "Activity type or status is unsupported"
+  );
+  parseIsoTimestamp(entry.occurredAt);
+  economyAssert(
+    parseTokenSubunits(entry.amount) !== 0n,
+    "INVALID_AMOUNT",
+    "Activity entries cannot contain a zero amount"
+  );
+  if (entry.beneficiaryAccountId !== void 0) {
+    assertEconomyIdentifier(
+      entry.beneficiaryAccountId,
+      "beneficiaryAccountId"
+    );
+  }
+  if (entry.maskedReference !== void 0) {
+    economyAssert(
+      entry.maskedReference.length > 0 && entry.maskedReference.length <= 128 && !hasControlCharacters(entry.maskedReference),
+      "INVALID_CONTRACT",
+      "Masked activity references must be bounded and safe for display"
+    );
+  }
+  economyAssert(
+    entry.sourceLabel.trim().length > 0 && entry.sourceLabel.length <= 128 && !hasControlCharacters(entry.sourceLabel),
+    "INVALID_CONTRACT",
+    "Activity source labels must be bounded and safe for display"
+  );
+}
+function assertBalancedTransaction(transaction) {
+  economyAssert(
+    transaction.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported ledger contract version"
+  );
+  assertEconomyIdentifier(transaction.transactionId, "transactionId");
+  assertEconomyIdentifier(transaction.idempotencyKey, "idempotencyKey");
+  economyAssert(
+    ACTIVITY_TYPES.has(transaction.activityType) && ACTIVITY_STATUSES.has(transaction.status),
+    "INVALID_CONTRACT",
+    "Transaction activity type or status is unsupported"
+  );
+  if (transaction.providerEventId !== void 0) {
+    assertEconomyIdentifier(transaction.providerEventId, "providerEventId");
+  }
+  if (transaction.reversesTransactionId !== void 0) {
+    assertEconomyIdentifier(
+      transaction.reversesTransactionId,
+      "reversesTransactionId"
+    );
+  }
+  economyAssert(
+    transaction.activityType === "reversal" === (transaction.reversesTransactionId !== void 0),
+    "INVALID_CONTRACT",
+    "Reversal transactions must identify exactly one original transaction"
+  );
+  const effectiveAt = parseIsoTimestamp(transaction.effectiveAt);
+  const recordedAt = parseIsoTimestamp(transaction.recordedAt);
+  economyAssert(
+    recordedAt >= effectiveAt,
+    "INVALID_TIME_WINDOW",
+    "Transaction recording time cannot precede its effective time"
+  );
+  if (transaction.previousCanonicalHash !== void 0) {
+    assertCanonicalHash(
+      transaction.previousCanonicalHash,
+      "Previous canonical hash"
+    );
+  }
+  if (transaction.canonicalHash !== void 0) {
+    assertCanonicalHash(transaction.canonicalHash, "Canonical hash");
+  }
+  const metadataEntries = Object.entries(transaction.metadata);
+  economyAssert(
+    metadataEntries.length <= 32 && metadataEntries.every(
+      ([key, value]) => /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u.test(key) && value.length <= 512 && !hasControlCharacters(value)
+    ),
+    "INVALID_CONTRACT",
+    "Transaction metadata must be bounded and free of control characters"
+  );
+  economyAssert(
+    transaction.postings.length >= 2,
+    "UNBALANCED_TRANSACTION",
+    "A ledger transaction needs at least two postings"
+  );
+  const postingIds = /* @__PURE__ */ new Set();
+  for (const posting of transaction.postings) {
+    economyAssert(
+      posting.schemaVersion === ECONOMY_CONTRACT_VERSION,
+      "INVALID_CONTRACT",
+      "Unsupported posting contract version"
+    );
+    assertEconomyIdentifier(posting.postingId, "postingId");
+    assertEconomyIdentifier(posting.accountId, "accountId");
+    if (posting.walletId !== void 0) {
+      assertEconomyIdentifier(posting.walletId, "walletId");
+    }
+    if (posting.lotId !== void 0) {
+      assertEconomyIdentifier(posting.lotId, "lotId");
+    }
+    economyAssert(
+      posting.transactionId === transaction.transactionId,
+      "INVALID_CONTRACT",
+      "Posting transactionId must match its transaction"
+    );
+    economyAssert(
+      !postingIds.has(posting.postingId),
+      "DUPLICATE_IDENTIFIER",
+      "Posting identifiers must be unique within a transaction"
+    );
+    postingIds.add(posting.postingId);
+    economyAssert(
+      parseTokenSubunits(posting.amount) !== 0n,
+      "INVALID_AMOUNT",
+      "Zero-value postings are not permitted"
+    );
+  }
+  economyAssert(
+    sumTokenSubunits(transaction.postings.map((posting) => posting.amount)) === 0n,
+    "UNBALANCED_TRANSACTION",
+    "Ledger postings must sum to zero TokenSubunits"
+  );
+}
+function canonicalTransactionPayload(transaction) {
+  assertBalancedTransaction(transaction);
+  const postings = [...transaction.postings].sort((left, right) => left.postingId.localeCompare(right.postingId)).map((posting) => ({
+    schemaVersion: posting.schemaVersion,
+    postingId: posting.postingId,
+    transactionId: posting.transactionId,
+    accountId: posting.accountId,
+    ...posting.walletId === void 0 ? {} : { walletId: posting.walletId },
+    ...posting.lotId === void 0 ? {} : { lotId: posting.lotId },
+    amount: posting.amount
+  }));
+  return JSON.stringify({
+    schemaVersion: transaction.schemaVersion,
+    transactionId: transaction.transactionId,
+    activityType: transaction.activityType,
+    status: transaction.status,
+    idempotencyKey: transaction.idempotencyKey,
+    ...transaction.providerEventId === void 0 ? {} : { providerEventId: transaction.providerEventId },
+    ...transaction.reversesTransactionId === void 0 ? {} : { reversesTransactionId: transaction.reversesTransactionId },
+    effectiveAt: transaction.effectiveAt,
+    recordedAt: transaction.recordedAt,
+    ...transaction.previousCanonicalHash === void 0 ? {} : { previousCanonicalHash: transaction.previousCanonicalHash },
+    metadata: sortStringRecord(transaction.metadata),
+    postings
+  });
+}
+function createReversalTransaction(original, input) {
+  assertBalancedTransaction(original);
+  economyAssert(
+    original.reversesTransactionId === void 0,
+    "INVALID_CONTRACT",
+    "A reversal cannot itself be reversed by this helper"
+  );
+  economyAssert(
+    input.postingIds.length === original.postings.length,
+    "INVALID_CONTRACT",
+    "A reversal needs one new posting identifier per original posting"
+  );
+  const postings = original.postings.map((posting, index) => {
+    const postingId = input.postingIds[index];
+    economyAssert(
+      postingId !== void 0,
+      "INVALID_CONTRACT",
+      "Missing reversal posting identifier"
+    );
+    return {
+      ...posting,
+      postingId,
+      transactionId: input.transactionId,
+      amount: serializeTokenSubunits(-parseTokenSubunits(posting.amount))
+    };
+  });
+  const transaction = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    transactionId: input.transactionId,
+    activityType: "reversal",
+    status: "settled",
+    idempotencyKey: input.idempotencyKey,
+    reversesTransactionId: original.transactionId,
+    effectiveAt: input.effectiveAt,
+    recordedAt: input.recordedAt,
+    ...input.previousCanonicalHash === void 0 ? {} : { previousCanonicalHash: input.previousCanonicalHash },
+    metadata: input.metadata ?? {},
+    postings
+  };
+  assertBalancedTransaction(transaction);
+  return transaction;
+}
+function assertReversalAvailable(originalTransactionId, existingTransactions) {
+  assertEconomyIdentifier(originalTransactionId, "originalTransactionId");
+  economyAssert(
+    !existingTransactions.some(
+      (transaction) => transaction.reversesTransactionId === originalTransactionId && transaction.status !== "failed"
+    ),
+    "REVERSAL_ALREADY_EXISTS",
+    "The transaction already has an effective reversal"
+  );
+}
+
+// src/lots.ts
+function assertSourceLot(lot) {
+  economyAssert(
+    lot.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported source-lot contract version"
+  );
+  assertEconomyIdentifier(lot.lotId, "lotId");
+  assertEconomyIdentifier(lot.walletId, "walletId");
+  assertEconomyIdentifier(lot.beneficiaryAccountId, "beneficiaryAccountId");
+  if (lot.householdId !== void 0) {
+    assertEconomyIdentifier(lot.householdId, "householdId");
+  }
+  if (lot.payerAccountId !== void 0) {
+    assertEconomyIdentifier(lot.payerAccountId, "payerAccountId");
+  }
+  if (lot.providerEventId !== void 0) {
+    assertEconomyIdentifier(lot.providerEventId, "providerEventId");
+  }
+  assertEconomyIdentifier(lot.rateVersion, "rateVersion");
+  economyAssert(
+    [
+      "shopify",
+      "ayet",
+      "bitlabs",
+      "subscription",
+      "event",
+      "competition",
+      "adjustment"
+    ].includes(lot.source),
+    "INVALID_CONTRACT",
+    "Source lot has an unsupported source"
+  );
+  economyAssert(
+    ["household-allocatable", "same-user-only", "non-transferable"].includes(
+      lot.transferPolicy
+    ),
+    "INVALID_CONTRACT",
+    "Source lot has an unsupported transfer policy"
+  );
+  economyAssert(
+    ["none", "partial", "refunded", "disputed", "chargeback-lost"].includes(
+      lot.refundState
+    ),
+    "INVALID_CONTRACT",
+    "Source lot has an unsupported refund state"
+  );
+  if (lot.source === "ayet" || lot.source === "bitlabs") {
+    economyAssert(
+      lot.transferPolicy === "same-user-only" && lot.providerEventId !== void 0,
+      "SOURCE_LOT_RESTRICTED",
+      "Reward-provider lots must remain with the earning account"
+    );
+  }
+  if (lot.source === "shopify") {
+    economyAssert(
+      lot.transferPolicy === "household-allocatable" && lot.householdId !== void 0 && lot.payerAccountId !== void 0,
+      "INVALID_CONTRACT",
+      "Shopify lots must retain payer and receiving-household provenance"
+    );
+  }
+  economyAssert(
+    /^sha256:[a-f0-9]{64}$/u.test(lot.settlementEvidenceHash),
+    "INVALID_CONTRACT",
+    "Settlement evidence must be a sanitized SHA-256 reference"
+  );
+  const settledAt = parseIsoTimestamp(lot.settledAt);
+  const creditedAt = parseIsoTimestamp(lot.creditedAt);
+  economyAssert(
+    creditedAt >= settledAt,
+    "INVALID_TIME_WINDOW",
+    "Source-lot credit time cannot precede settlement"
+  );
+  if (lot.cohortKey !== void 0) {
+    assertEconomyIdentifier(lot.cohortKey, "cohortKey");
+  }
+  const original = parseTokenSubunits(lot.originalAmount);
+  const remaining = parseTokenSubunits(lot.remainingAmount);
+  const held = parseTokenSubunits(lot.heldAmount);
+  const reversed = parseTokenSubunits(lot.reversedAmount);
+  economyAssert(
+    original > 0n && remaining >= 0n && held >= 0n && reversed >= 0n,
+    "INVALID_AMOUNT",
+    "Source-lot amounts must be non-negative and original must be positive"
+  );
+  economyAssert(
+    remaining <= original && held <= remaining && reversed <= original,
+    "INVALID_CONTRACT",
+    "Source-lot amount components exceed the original or remaining amount"
+  );
+  economyAssert(
+    remaining + reversed <= original,
+    "INVALID_CONTRACT",
+    "Remaining and reversed source-lot amounts exceed the original"
+  );
+}
+function availableSourceLotAmount(lot) {
+  assertSourceLot(lot);
+  return parseTokenSubunits(lot.remainingAmount) - parseTokenSubunits(lot.heldAmount);
+}
+function canUseSourceLot(lot, context) {
+  if (context.operation === "refund") {
+    return true;
+  }
+  if (context.operation === "allocate" || context.operation === "reclaim") {
+    return lot.transferPolicy === "household-allocatable" && lot.householdId !== void 0 && lot.householdId === context.householdId;
+  }
+  if (lot.transferPolicy === "household-allocatable") {
+    return lot.householdId !== void 0 && lot.householdId === context.householdId;
+  }
+  return lot.beneficiaryAccountId === context.beneficiaryAccountId;
+}
+function selectSourceLots(lots, requestedAmount, context) {
+  const requested = parseTokenSubunits(requestedAmount);
+  economyAssert(
+    requested > 0n,
+    "INVALID_AMOUNT",
+    "Requested source-lot amount must be positive"
+  );
+  assertEconomyIdentifier(context.beneficiaryAccountId, "beneficiaryAccountId");
+  const ordered = [...lots].sort((left, right) => {
+    const timeDifference = parseIsoTimestamp(left.creditedAt) - parseIsoTimestamp(right.creditedAt);
+    return timeDifference === 0 ? left.lotId.localeCompare(right.lotId) : timeDifference;
+  });
+  let allAvailable = 0n;
+  let remaining = requested;
+  const slices = [];
+  for (const lot of ordered) {
+    const available = availableSourceLotAmount(lot);
+    allAvailable += available;
+    if (available === 0n || !canUseSourceLot(lot, context)) {
+      continue;
+    }
+    const selected = available < remaining ? available : remaining;
+    slices.push({ lotId: lot.lotId, amount: serializeTokenSubunits(selected) });
+    remaining -= selected;
+    if (remaining === 0n) {
+      return slices;
+    }
+  }
+  if (allAvailable >= requested) {
+    throw new EconomyError(
+      "SOURCE_LOT_RESTRICTED",
+      "Available source lots do not permit this operation"
+    );
+  }
+  throw new EconomyError(
+    "INSUFFICIENT_ELIGIBLE_LOTS",
+    "Insufficient eligible source-lot balance"
+  );
+}
+
+// src/operations.ts
+function assertDistinctAdjustmentApproval(request) {
+  economyAssert(
+    request.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported adjustment contract version"
+  );
+  assertEconomyIdentifier(request.adjustmentId, "adjustmentId");
+  assertEconomyIdentifier(request.walletId, "walletId");
+  assertEconomyIdentifier(request.initiatedByAccountId, "initiatedByAccountId");
+  economyAssert(
+    parseTokenSubunits(request.amount) !== 0n,
+    "INVALID_AMOUNT",
+    "Adjustment amount cannot be zero"
+  );
+  economyAssert(
+    request.reason.trim().length > 0 && request.reason.length <= 512,
+    "INVALID_CONTRACT",
+    "Adjustment reason is required and must be bounded"
+  );
+  assertEconomyIdentifier(request.ticketReference, "ticketReference");
+  const initiatedAt = parseIsoTimestamp(request.initiatedAt);
+  economyAssert(
+    request.approvedByAccountId !== void 0 && request.approvedByAccountId !== request.initiatedByAccountId,
+    "INVALID_CONTRACT",
+    "Adjustment approval requires a distinct authorized operator"
+  );
+  assertEconomyIdentifier(request.approvedByAccountId, "approvedByAccountId");
+  economyAssert(
+    request.approvedAt !== void 0 && parseIsoTimestamp(request.approvedAt) >= initiatedAt,
+    "INVALID_TIME_WINDOW",
+    "Adjustment approval time must follow initiation"
+  );
+  economyAssert(
+    request.status === "approved" || request.status === "executed",
+    "INVALID_CONTRACT",
+    "Only approved adjustments satisfy dual-control approval"
+  );
+  if (request.resultingTransactionId !== void 0) {
+    assertEconomyIdentifier(
+      request.resultingTransactionId,
+      "resultingTransactionId"
+    );
+  }
+}
+
+// src/projection.ts
+function applyTransactionToProjection(current, transaction) {
+  assertBalancedTransaction(transaction);
+  const next = { ...current };
+  for (const posting of transaction.postings) {
+    const prior = parseTokenSubunits(next[posting.accountId] ?? "0");
+    next[posting.accountId] = serializeTokenSubunits(
+      prior + parseTokenSubunits(posting.amount)
+    );
+  }
+  return next;
+}
+function rebuildBalanceProjection(transactions) {
+  let projection = {};
+  const transactionIds = /* @__PURE__ */ new Set();
+  const idempotencyKeys = /* @__PURE__ */ new Set();
+  const providerEvents = /* @__PURE__ */ new Set();
+  for (const transaction of transactions) {
+    economyAssert(
+      !transactionIds.has(transaction.transactionId),
+      "DUPLICATE_TRANSACTION",
+      "Transaction identifiers must be unique"
+    );
+    economyAssert(
+      !idempotencyKeys.has(transaction.idempotencyKey),
+      "DUPLICATE_TRANSACTION",
+      "Idempotency keys must be unique"
+    );
+    if (transaction.providerEventId !== void 0) {
+      economyAssert(
+        !providerEvents.has(transaction.providerEventId),
+        "DUPLICATE_TRANSACTION",
+        "Provider event identifiers must be unique"
+      );
+      providerEvents.add(transaction.providerEventId);
+    }
+    transactionIds.add(transaction.transactionId);
+    idempotencyKeys.add(transaction.idempotencyKey);
+    projection = applyTransactionToProjection(projection, transaction);
+  }
+  return projection;
+}
+function assertNonNegativeAccounts(projection, protectedAccountIds) {
+  for (const accountId of protectedAccountIds) {
+    economyAssert(
+      parseTokenSubunits(projection[accountId] ?? "0") >= 0n,
+      "NEGATIVE_PROJECTION",
+      "A protected economy account would become negative"
+    );
+  }
+}
+function createProjectionSnapshot(transactions, rebuiltAt) {
+  parseIsoTimestamp(rebuiltAt);
+  const last = transactions.at(-1);
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    balances: rebuildBalanceProjection(transactions),
+    ...last === void 0 ? {} : { lastTransactionId: last.transactionId },
+    rebuiltAt
+  };
+}
+
+// src/recurrence.ts
+var BASELINE_MONTHLY_SUBSCRIPTION_PLAN = Object.freeze({
+  schemaVersion: ECONOMY_CONTRACT_VERSION,
+  planId: "monthly-10-100-v1",
+  catalogVersion: "gbp-subscriptions-v1",
+  interval: "monthly",
+  priceMinorUnits: "1000",
+  currency: "GBP",
+  grantAmount: serializeTokenSubunits(100000n),
+  enabled: false,
+  effectiveFrom: "2026-07-15T00:00:00.000Z"
+});
+function assertTokenSubscriptionPlan(plan) {
+  economyAssert(
+    plan.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported subscription-plan contract version"
+  );
+  assertEconomyIdentifier(plan.planId, "planId");
+  assertEconomyIdentifier(plan.catalogVersion, "catalogVersion");
+  economyAssert(
+    ["daily", "weekly", "monthly"].includes(plan.interval) && plan.currency === "GBP" && typeof plan.enabled === "boolean",
+    "INVALID_CONTRACT",
+    "Subscription recurrence, currency, or enabled state is invalid"
+  );
+  economyAssert(
+    /^(?:0|[1-9][0-9]*)$/u.test(plan.priceMinorUnits) && BigInt(plan.priceMinorUnits) > 0n,
+    "INVALID_AMOUNT",
+    "Subscription price must be a positive integer minor-unit string"
+  );
+  const grantAmount = parseTokenSubunits(plan.grantAmount);
+  economyAssert(
+    grantAmount > 0n && isWholeTokenAmount(grantAmount),
+    "AMOUNT_NOT_WHOLE_TOKEN",
+    "Subscription grants must contain whole Tokens"
+  );
+  parseIsoTimestamp(plan.effectiveFrom);
+}
+
+// src/spend-requests.ts
+function assertSpendRequest(request) {
+  economyAssert(
+    request.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported spend-request contract version"
+  );
+  assertEconomyIdentifier(request.requestId, "requestId");
+  assertEconomyIdentifier(request.childAccountId, "childAccountId");
+  assertEconomyIdentifier(request.allocationId, "allocationId");
+  economyAssert(
+    request.purpose === "gameplay-conversion" || request.purpose === "non-gameplay",
+    "INVALID_CONTRACT",
+    "Spend request has an unsupported purpose"
+  );
+  economyAssert(
+    [
+      "requested",
+      "approved",
+      "rejected",
+      "expired",
+      "executed",
+      "cancelled"
+    ].includes(request.status),
+    "INVALID_CONTRACT",
+    "Spend request has an unsupported status"
+  );
+  economyAssert(
+    parseTokenSubunits(request.amount) > 0n,
+    "INVALID_AMOUNT",
+    "Spend-request amount must be positive"
+  );
+  const requestedAt = parseIsoTimestamp(request.requestedAt);
+  const expiresAt = parseIsoTimestamp(request.expiresAt);
+  economyAssert(
+    expiresAt > requestedAt,
+    "INVALID_TIME_WINDOW",
+    "Spend-request expiry must follow creation"
+  );
+  const decisionRequired = ["approved", "rejected", "executed"].includes(
+    request.status
+  );
+  economyAssert(
+    !decisionRequired || request.decidedByAccountId !== void 0 && request.decidedAt !== void 0,
+    "INVALID_CONTRACT",
+    "Decided spend requests require a guardian actor and timestamp"
+  );
+  if (request.decidedByAccountId !== void 0) {
+    assertEconomyIdentifier(request.decidedByAccountId, "decidedByAccountId");
+  }
+  if (request.decidedAt !== void 0) {
+    const decidedAt = parseIsoTimestamp(request.decidedAt);
+    economyAssert(
+      decidedAt >= requestedAt && decidedAt <= expiresAt,
+      "INVALID_TIME_WINDOW",
+      "Spend-request decision must occur before expiry"
+    );
+  }
+  if (request.approvalNonceHash !== void 0) {
+    economyAssert(
+      /^sha256:[a-f0-9]{64}$/u.test(request.approvalNonceHash),
+      "INVALID_CONTRACT",
+      "Approval nonces must be stored as SHA-256 hashes"
+    );
+  }
+  if (request.status === "approved" || request.status === "executed") {
+    economyAssert(
+      request.approvalNonceHash !== void 0,
+      "INVALID_CONTRACT",
+      "Approved spend requests require a one-time approval nonce hash"
+    );
+  }
+  if (request.resultingTransactionId !== void 0) {
+    assertEconomyIdentifier(
+      request.resultingTransactionId,
+      "resultingTransactionId"
+    );
+    economyAssert(
+      request.status === "executed",
+      "INVALID_CONTRACT",
+      "Only executed spend requests may reference a ledger transaction"
+    );
+  }
+}
+
+// src/wallets.ts
+function assertWallet(wallet) {
+  economyAssert(
+    wallet.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet contract version"
+  );
+  assertEconomyIdentifier(wallet.walletId, "walletId");
+  assertEconomyIdentifier(wallet.accountId, "accountId");
+  economyAssert(
+    [
+      "household-treasury",
+      "personal",
+      "gameplay-allocation",
+      "hold",
+      "purchase-clearing",
+      "provider-clearing",
+      "system"
+    ].includes(wallet.kind),
+    "INVALID_CONTRACT",
+    "Wallet has an unsupported kind"
+  );
+  economyAssert(
+    ["account", "household", "system"].includes(wallet.ownerType),
+    "INVALID_CONTRACT",
+    "Wallet has an unsupported owner type"
+  );
+  economyAssert(
+    ["active", "restricted", "closed"].includes(wallet.status),
+    "INVALID_CONTRACT",
+    "Wallet has an unsupported status"
+  );
+  if (wallet.ownerType === "system") {
+    economyAssert(
+      wallet.ownerId === "system",
+      "INVALID_CONTRACT",
+      "System wallets must be owned by the system"
+    );
+  } else {
+    assertEconomyIdentifier(wallet.ownerId, "ownerId");
+  }
+  if (wallet.householdId !== void 0) {
+    assertEconomyIdentifier(wallet.householdId, "householdId");
+  }
+  if (wallet.ownerType === "household") {
+    economyAssert(
+      wallet.householdId === wallet.ownerId,
+      "INVALID_CONTRACT",
+      "Household wallets must identify the same household owner"
+    );
+  }
+  if (wallet.kind === "household-treasury") {
+    economyAssert(
+      wallet.ownerType === "household" && wallet.householdId !== void 0,
+      "INVALID_CONTRACT",
+      "Household treasuries must be owned by their household"
+    );
+  }
+  if (wallet.kind === "personal" || wallet.kind === "gameplay-allocation") {
+    economyAssert(
+      wallet.ownerType === "account",
+      "INVALID_CONTRACT",
+      "Personal and gameplay-allocation wallets must be account-owned"
+    );
+  }
+  if (wallet.kind === "gameplay-allocation") {
+    economyAssert(
+      wallet.householdId !== void 0,
+      "INVALID_CONTRACT",
+      "Gameplay-allocation wallets must retain household provenance"
+    );
+  }
+  if (wallet.kind === "purchase-clearing" || wallet.kind === "provider-clearing" || wallet.kind === "system") {
+    economyAssert(
+      wallet.ownerType === "system" && wallet.householdId === void 0,
+      "INVALID_CONTRACT",
+      "Clearing and system wallets must be system-owned"
+    );
+  }
+  economyAssert(
+    Number.isSafeInteger(wallet.version) && wallet.version >= 1,
+    "INVALID_CONTRACT",
+    "Wallet version must be a positive safe integer"
+  );
+  const createdAt = parseIsoTimestamp(wallet.createdAt);
+  if (wallet.closedAt !== void 0) {
+    economyAssert(
+      parseIsoTimestamp(wallet.closedAt) >= createdAt && wallet.status === "closed",
+      "INVALID_TIME_WINDOW",
+      "Only closed wallets may have a valid closure time"
+    );
+  } else {
+    economyAssert(
+      wallet.status !== "closed",
+      "INVALID_CONTRACT",
+      "Closed wallets require a closure time"
+    );
+  }
+}
+function assertWalletBalanceSummary(summary) {
+  economyAssert(
+    summary.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet summary contract version"
+  );
+  assertEconomyIdentifier(summary.walletId, "walletId");
+  for (const amount of [
+    summary.available,
+    summary.reserved,
+    summary.held,
+    summary.rewardProgress
+  ]) {
+    economyAssert(
+      parseTokenSubunits(amount) >= 0n,
+      "INVALID_AMOUNT",
+      "Wallet summary categories cannot be negative"
+    );
+  }
+  economyAssert(
+    Number.isSafeInteger(summary.version) && summary.version >= 1,
+    "INVALID_CONTRACT",
+    "Wallet summary version must be a positive safe integer"
+  );
+  parseIsoTimestamp(summary.asOf);
+}
+function assertWalletLifetimeTotals(totals) {
+  economyAssert(
+    totals.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet lifetime-total contract version"
+  );
+  for (const amount of [
+    totals.bought,
+    totals.earned,
+    totals.allocated,
+    totals.reclaimed,
+    totals.spent,
+    totals.reversed
+  ]) {
+    economyAssert(
+      parseTokenSubunits(amount) >= 0n,
+      "INVALID_AMOUNT",
+      "Wallet lifetime totals cannot be negative"
+    );
+  }
+}
+export {
+  BASELINE_GBP_CATALOG_VERSION,
+  BASELINE_GBP_REFERENCE_RATE,
+  BASELINE_GBP_TOKEN_PACKS,
+  BASELINE_MONTHLY_SUBSCRIPTION_PLAN,
+  BASELINE_PURCHASE_LIMIT_POLICY,
+  ECONOMY_CONTRACT_VERSION,
+  EconomyError,
+  PRE_UTILITY_BACKER_COHORT,
+  TOKEN_SUBUNITS_MAX,
+  TOKEN_SUBUNITS_MIN,
+  TOKEN_SUBUNITS_PER_TOKEN,
+  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
+};
+//# sourceMappingURL=index.js.map