@plasius/economy 0.2.0 → 0.3.1

package/dist/index.js

@@ -81,6 +81,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;
@@ -117,7 +125,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)
+    )
   );
 }
 
@@ -721,6 +731,7 @@ function reclaimGameplayAllocation(allocation, input) {
 
 // src/early-backers.ts
 var PRE_UTILITY_BACKER_COHORT = "pre_utility_backer_v1";
+var EARLY_BACKER_SETTLEMENT_POLICY_V2 = "settlement-window-v2";
 function isWithinWindow(timestamp, launch, cutoff) {
   const value = parseIsoTimestamp(timestamp);
   return value >= launch && (cutoff === void 0 || value < cutoff);
@@ -792,6 +803,71 @@ function evaluateEarlyBacker(payerAccountId, receivingHouseholdId, paidLots, win
     evaluatedAt
   };
 }
+function evaluateEarlyBackerBySettlementV2(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"
+  );
+  const evaluationTime = 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"
+    );
+    const amount = parseTokenSubunits(lot.retainedAmount);
+    economyAssert(
+      amount >= 0n,
+      "INVALID_AMOUNT",
+      "Retained paid-lot basis cannot be negative"
+    );
+    if (lot.payerAccountId === payerAccountId && lot.receivingHouseholdId === receivingHouseholdId && settledAt >= launch && (cutoff === void 0 || settledAt < cutoff) && settledAt <= evaluationTime && amount > 0n) {
+      retained += amount;
+      contributingLotIds.push(lot.lotId);
+    }
+  }
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    policyVersion: EARLY_BACKER_SETTLEMENT_POLICY_V2,
+    qualificationEvent: "settled-at",
+    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([
@@ -971,9 +1047,19 @@ function assertBalancedTransaction(transaction) {
     "Ledger postings must sum to zero TokenSubunits"
   );
 }
+function assertEconomicJournalTransaction(transaction) {
+  assertBalancedTransaction(transaction);
+  economyAssert(
+    transaction.status === "held" || transaction.status === "settled",
+    "INVALID_CONTRACT",
+    "Pending, failed, and derived reversed activity cannot be journal transactions"
+  );
+}
 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,
@@ -1050,6 +1136,71 @@ function assertReversalAvailable(originalTransactionId, existingTransactions) {
   );
 }
 
+// src/integrity.ts
+function assertCanonicalHash2(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 assertJournalChainHead(head) {
+  economyAssert(
+    head.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported journal-chain-head contract version"
+  );
+  assertEconomyIdentifier(head.chainId, "chainId");
+  economyAssert(
+    Number.isSafeInteger(head.version) && head.version >= 0,
+    "INVALID_CONTRACT",
+    "Journal-chain-head version must be a non-negative safe integer"
+  );
+  parseIsoTimestamp(head.updatedAt);
+  const hasTransaction = head.lastTransactionId !== void 0;
+  const hasHash = head.canonicalHash !== void 0;
+  economyAssert(
+    hasTransaction === hasHash && head.version > 0 === hasTransaction,
+    "INVALID_CONTRACT",
+    "Journal-chain head identity, hash, and version must describe the same state"
+  );
+  if (head.lastTransactionId !== void 0) {
+    assertEconomyIdentifier(head.lastTransactionId, "lastTransactionId");
+  }
+  if (head.canonicalHash !== void 0) {
+    assertCanonicalHash2(head.canonicalHash, "Journal-chain-head hash");
+  }
+}
+function advanceJournalChainHead(head, transaction) {
+  assertJournalChainHead(head);
+  assertEconomicJournalTransaction(transaction);
+  assertCanonicalHash2(transaction.canonicalHash, "Transaction hash");
+  economyAssert(
+    transaction.previousCanonicalHash === head.canonicalHash,
+    "INVALID_CONTRACT",
+    "Transaction previous hash must match the locked journal-chain head"
+  );
+  economyAssert(
+    transaction.canonicalHash !== head.canonicalHash,
+    "DUPLICATE_TRANSACTION",
+    "Transaction hash must advance the journal chain"
+  );
+  const recordedAt = parseIsoTimestamp(transaction.recordedAt);
+  economyAssert(
+    recordedAt >= parseIsoTimestamp(head.updatedAt),
+    "INVALID_TIME_WINDOW",
+    "Journal-chain update cannot precede its locked head"
+  );
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    chainId: head.chainId,
+    version: head.version + 1,
+    lastTransactionId: transaction.transactionId,
+    canonicalHash: transaction.canonicalHash,
+    updatedAt: transaction.recordedAt
+  };
+}
+
 // src/lots.ts
 function assertSourceLot(lot) {
   economyAssert(
@@ -1146,6 +1297,199 @@ function assertSourceLot(lot) {
     "Remaining and reversed source-lot amounts exceed the original"
   );
 }
+function assertVersionedSourceLot(snapshot) {
+  economyAssert(
+    snapshot.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported versioned source-lot contract version"
+  );
+  assertSourceLot(snapshot.lot);
+  economyAssert(
+    Number.isSafeInteger(snapshot.version) && snapshot.version >= 1,
+    "INVALID_CONTRACT",
+    "Source-lot version must be a positive safe integer"
+  );
+  economyAssert(
+    parseIsoTimestamp(snapshot.updatedAt) >= parseIsoTimestamp(snapshot.lot.creditedAt),
+    "INVALID_TIME_WINDOW",
+    "Source-lot update time cannot precede its credit"
+  );
+}
+function createInitialSourceLotSnapshot(lot) {
+  assertSourceLot(lot);
+  economyAssert(
+    lot.refundState === "none" && lot.originalAmount === lot.remainingAmount && parseTokenSubunits(lot.heldAmount) === 0n && parseTokenSubunits(lot.reversedAmount) === 0n,
+    "INVALID_CONTRACT",
+    "A new source lot must start fully remaining, clear, and unreversed"
+  );
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    lot,
+    version: 1,
+    updatedAt: lot.creditedAt
+  };
+}
+function assertRefundState(value) {
+  economyAssert(
+    [
+      "none",
+      "partial",
+      "refunded",
+      "disputed",
+      "chargeback-lost"
+    ].includes(value),
+    "INVALID_CONTRACT",
+    "Source-lot movement has an unsupported refund state"
+  );
+}
+function assertSourceLotMovement(movement) {
+  economyAssert(
+    movement.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported source-lot-movement contract version"
+  );
+  assertEconomyIdentifier(movement.movementId, "movementId");
+  assertEconomyIdentifier(movement.transactionId, "transactionId");
+  assertEconomyIdentifier(movement.lotId, "lotId");
+  economyAssert(
+    [
+      "allocate",
+      "boost",
+      "reclaim",
+      "spend",
+      "hold",
+      "release-hold",
+      "refund",
+      "chargeback",
+      "reversal"
+    ].includes(movement.movementType),
+    "INVALID_CONTRACT",
+    "Source-lot movement has an unsupported type"
+  );
+  const remaining = parseTokenSubunits(movement.remainingDelta);
+  const held = parseTokenSubunits(movement.heldDelta);
+  const reversed = parseTokenSubunits(movement.reversedDelta);
+  economyAssert(
+    remaining !== 0n || held !== 0n || reversed !== 0n,
+    "INVALID_AMOUNT",
+    "Source-lot movement must change at least one amount"
+  );
+  economyAssert(
+    Number.isSafeInteger(movement.expectedVersion) && movement.expectedVersion >= 1 && movement.resultingVersion === movement.expectedVersion + 1,
+    "INVALID_CONTRACT",
+    "Source-lot movement must advance its optimistic version exactly once"
+  );
+  assertRefundState(movement.expectedRefundState);
+  assertRefundState(movement.resultingRefundState);
+  parseIsoTimestamp(movement.occurredAt);
+  if (movement.movementType === "allocate" || movement.movementType === "boost" || movement.movementType === "spend") {
+    economyAssert(
+      remaining < 0n && held === 0n && reversed === 0n && movement.resultingRefundState === movement.expectedRefundState,
+      "INVALID_CONTRACT",
+      "Allocation, boost, and spend movements only consume remaining lot value"
+    );
+  } else if (movement.movementType === "reclaim") {
+    economyAssert(
+      remaining > 0n && held === 0n && reversed === 0n && movement.resultingRefundState === movement.expectedRefundState,
+      "INVALID_CONTRACT",
+      "Reclaim movements only restore remaining lot value"
+    );
+  } else if (movement.movementType === "hold") {
+    economyAssert(
+      remaining === 0n && held > 0n && reversed === 0n && movement.resultingRefundState === "disputed",
+      "INVALID_CONTRACT",
+      "Hold movements must enter disputed state and increase held value"
+    );
+  } else if (movement.movementType === "release-hold") {
+    economyAssert(
+      remaining === 0n && held < 0n && reversed === 0n && movement.expectedRefundState === "disputed" && movement.resultingRefundState !== "disputed" && movement.resultingRefundState !== "refunded" && movement.resultingRefundState !== "chargeback-lost",
+      "INVALID_CONTRACT",
+      "Released holds must leave disputed state without reversing value"
+    );
+  } else {
+    economyAssert(
+      remaining < 0n && reversed === -remaining && held <= 0n && (movement.resultingRefundState === "partial" || movement.resultingRefundState === "refunded" || movement.resultingRefundState === "chargeback-lost"),
+      "INVALID_CONTRACT",
+      "Refund, chargeback, and reversal movements must compensate remaining value exactly"
+    );
+    if (movement.movementType === "chargeback") {
+      economyAssert(
+        movement.resultingRefundState === "chargeback-lost",
+        "INVALID_CONTRACT",
+        "Chargeback movements must enter chargeback-lost state"
+      );
+    } else {
+      economyAssert(
+        movement.resultingRefundState !== "chargeback-lost",
+        "INVALID_CONTRACT",
+        "Only a chargeback movement may enter chargeback-lost state"
+      );
+    }
+  }
+}
+function applySourceLotMovement(snapshot, movement) {
+  assertVersionedSourceLot(snapshot);
+  assertSourceLotMovement(movement);
+  economyAssert(
+    movement.lotId === snapshot.lot.lotId && movement.expectedVersion === snapshot.version && movement.expectedRefundState === snapshot.lot.refundState,
+    "INVALID_CONTRACT",
+    "Source-lot movement does not match the locked lot version and refund state"
+  );
+  economyAssert(
+    parseIsoTimestamp(movement.occurredAt) >= parseIsoTimestamp(snapshot.updatedAt),
+    "INVALID_TIME_WINDOW",
+    "Source-lot movement cannot precede its current projection"
+  );
+  const lot = {
+    ...snapshot.lot,
+    remainingAmount: serializeTokenSubunits(
+      parseTokenSubunits(snapshot.lot.remainingAmount) + parseTokenSubunits(movement.remainingDelta)
+    ),
+    heldAmount: serializeTokenSubunits(
+      parseTokenSubunits(snapshot.lot.heldAmount) + parseTokenSubunits(movement.heldDelta)
+    ),
+    reversedAmount: serializeTokenSubunits(
+      parseTokenSubunits(snapshot.lot.reversedAmount) + parseTokenSubunits(movement.reversedDelta)
+    ),
+    refundState: movement.resultingRefundState
+  };
+  assertSourceLot(lot);
+  const remaining = parseTokenSubunits(lot.remainingAmount);
+  const held = parseTokenSubunits(lot.heldAmount);
+  const reversed = parseTokenSubunits(lot.reversedAmount);
+  const original = parseTokenSubunits(lot.originalAmount);
+  if (lot.refundState === "none") {
+    economyAssert(
+      reversed === 0n && held === 0n,
+      "INVALID_CONTRACT",
+      "A clear lot cannot retain held or reversed value"
+    );
+  } else if (lot.refundState === "partial") {
+    economyAssert(
+      reversed > 0n && remaining > 0n && held === 0n,
+      "INVALID_CONTRACT",
+      "A partial refund requires retained/reversed value and no active hold"
+    );
+  } else if (lot.refundState === "disputed") {
+    economyAssert(
+      held > 0n,
+      "INVALID_CONTRACT",
+      "A disputed lot must hold affected value"
+    );
+  } else {
+    economyAssert(
+      remaining === 0n && held === 0n && reversed === original,
+      "INVALID_CONTRACT",
+      "Final refund and lost-chargeback states must reverse the full lot"
+    );
+  }
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    lot,
+    version: movement.resultingVersion,
+    updatedAt: movement.occurredAt
+  };
+}
 function availableSourceLotAmount(lot) {
   assertSourceLot(lot);
   return parseTokenSubunits(lot.remainingAmount) - parseTokenSubunits(lot.heldAmount);
@@ -1248,193 +1592,137 @@ function assertDistinctAdjustmentApproval(request) {
   }
 }
 
-// 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;
+// src/ports/persistence.ts
+function assertScopedPersistedIdempotencyResult(result) {
+  economyAssert(
+    result.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported scoped idempotency-result contract version"
+  );
+  assertEconomyIdentifier(result.commandId, "commandId");
+  assertEconomyIdentifier(result.transactionId, "transactionId");
+  economyAssert(
+    /^sha256:[a-f0-9]{64}$/u.test(result.responseHash),
+    "INVALID_CONTRACT",
+    "Idempotency response hash must be a canonical SHA-256 reference"
+  );
+  parseIsoTimestamp(result.recordedAt);
 }
-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"
-    );
+var ECONOMY_COMMAND_TYPES = /* @__PURE__ */ new Set([
+  "credit-purchase",
+  "credit-subscription",
+  "credit-reward",
+  "credit-event",
+  "credit-competition",
+  "allocate",
+  "boost",
+  "reclaim",
+  "spend",
+  "hold",
+  "release-hold",
+  "refund",
+  "chargeback",
+  "reverse",
+  "adjust"
+]);
+function assertEconomyIdempotencyScope(scope) {
+  economyAssert(
+    scope.schemaVersion === ECONOMY_CONTRACT_VERSION && ECONOMY_COMMAND_TYPES.has(scope.commandType),
+    "INVALID_CONTRACT",
+    "Unsupported economy idempotency scope"
+  );
+  assertEconomyIdentifier(scope.idempotencyKey, "idempotencyKey");
+  assertEconomyIdentifier(scope.actorAccountId, "actorAccountId");
+  assertEconomyIdentifier(scope.subjectAccountId, "subjectAccountId");
+}
+function assertEconomyCommandEnvelope(envelope) {
+  economyAssert(
+    envelope.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported economy-command-envelope contract version"
+  );
+  assertEconomyIdentifier(envelope.commandId, "commandId");
+  economyAssert(
+    ECONOMY_COMMAND_TYPES.has(envelope.commandType),
+    "INVALID_CONTRACT",
+    "Economy command has an unsupported type"
+  );
+  assertEconomyIdentifier(envelope.idempotencyKey, "idempotencyKey");
+  assertEconomyIdentifier(envelope.actorAccountId, "actorAccountId");
+  assertEconomyIdentifier(envelope.subjectAccountId, "subjectAccountId");
+  if (envelope.relationshipId !== void 0) {
+    assertEconomyIdentifier(envelope.relationshipId, "relationshipId");
+  }
+  if (envelope.authorizationVersion !== void 0) {
     economyAssert(
-      !idempotencyKeys.has(transaction.idempotencyKey),
-      "DUPLICATE_TRANSACTION",
-      "Idempotency keys must be unique"
+      Number.isSafeInteger(envelope.authorizationVersion) && envelope.authorizationVersion >= 1,
+      "INVALID_CONTRACT",
+      "Command authorization version must be a positive safe integer"
     );
-    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,
+    envelope.relationshipId === void 0 === (envelope.authorizationVersion === void 0),
     "INVALID_CONTRACT",
-    "Unsupported subscription-plan contract version"
+    "Relationship identity and authorization version must be supplied together"
   );
-  assertEconomyIdentifier(plan.planId, "planId");
-  assertEconomyIdentifier(plan.catalogVersion, "catalogVersion");
   economyAssert(
-    ["daily", "weekly", "monthly"].includes(plan.interval) && plan.currency === "GBP" && typeof plan.enabled === "boolean",
+    /^sha256:[a-f0-9]{64}$/u.test(envelope.payloadHash),
     "INVALID_CONTRACT",
-    "Subscription recurrence, currency, or enabled state is invalid"
+    "Command payload hash must be a canonical SHA-256 reference"
   );
-  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(envelope.acceptedAt);
+  assertEconomyIdentifier(envelope.acceptedRegion, "acceptedRegion");
+  assertEconomyIdentifier(
+    envelope.writerFencingToken,
+    "writerFencingToken"
   );
-  parseIsoTimestamp(plan.effectiveFrom);
 }
-
-// src/spend-requests.ts
-function assertSpendRequest(request) {
+function assertEconomyCommandWorkflowEvent(event) {
   economyAssert(
-    request.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    event.schemaVersion === ECONOMY_CONTRACT_VERSION,
     "INVALID_CONTRACT",
-    "Unsupported spend-request contract version"
+    "Unsupported command-workflow-event contract version"
   );
-  assertEconomyIdentifier(request.requestId, "requestId");
-  assertEconomyIdentifier(request.childAccountId, "childAccountId");
-  assertEconomyIdentifier(request.allocationId, "allocationId");
+  assertEconomyIdentifier(event.workflowEventId, "workflowEventId");
+  assertEconomyIdentifier(event.commandId, "commandId");
   economyAssert(
-    request.purpose === "gameplay-conversion" || request.purpose === "non-gameplay",
+    ["accepted", "processing", "failed", "completed"].includes(event.state),
     "INVALID_CONTRACT",
-    "Spend request has an unsupported purpose"
+    "Command workflow has an unsupported state"
   );
   economyAssert(
-    [
-      "requested",
-      "approved",
-      "rejected",
-      "expired",
-      "executed",
-      "cancelled"
-    ].includes(request.status),
+    event.state === "failed" === (event.failureCode !== void 0),
     "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
+    "Only failed command workflows require a failure code"
   );
+  if (event.failureCode !== void 0) {
+    assertEconomyIdentifier(event.failureCode, "failureCode");
+  }
+  parseIsoTimestamp(event.occurredAt);
+}
+
+// src/wallets.ts
+function assertWalletOwnerReference(owner) {
   economyAssert(
-    !decisionRequired || request.decidedByAccountId !== void 0 && request.decidedAt !== void 0,
+    ["account", "household", "system"].includes(owner.ownerType),
     "INVALID_CONTRACT",
-    "Decided spend requests require a guardian actor and timestamp"
+    "Wallet owner reference has an unsupported type"
   );
-  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) {
+  if (owner.ownerType === "system") {
     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,
+      owner.ownerId === "system",
       "INVALID_CONTRACT",
-      "Approved spend requests require a one-time approval nonce hash"
-    );
-  }
-  if (request.resultingTransactionId !== void 0) {
-    assertEconomyIdentifier(
-      request.resultingTransactionId,
-      "resultingTransactionId"
+      "System wallet lookups must use the system owner"
     );
+  } else {
+    assertEconomyIdentifier(owner.ownerId, "ownerId");
     economyAssert(
-      request.status === "executed",
+      owner.ownerId !== "system",
       "INVALID_CONTRACT",
-      "Only executed spend requests may reference a ledger transaction"
+      "Account and household wallets cannot use the system owner"
     );
   }
 }
-
-// src/wallets.ts
 function assertWallet(wallet) {
   economyAssert(
     wallet.schemaVersion === ECONOMY_CONTRACT_VERSION,
@@ -1580,26 +1868,951 @@ function assertWalletLifetimeTotals(totals) {
     );
   }
 }
+
+// src/projection.ts
+function assertWalletBalanceProjection(projection) {
+  economyAssert(
+    projection.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet-balance-projection contract version"
+  );
+  assertEconomyIdentifier(projection.walletId, "walletId");
+  for (const amount of [
+    projection.spendable,
+    projection.reserved,
+    projection.held
+  ]) {
+    economyAssert(
+      parseTokenSubunits(amount) >= 0n,
+      "NEGATIVE_PROJECTION",
+      "Wallet projection buckets cannot be negative"
+    );
+  }
+  economyAssert(
+    Number.isSafeInteger(projection.version) && projection.version >= 1,
+    "INVALID_CONTRACT",
+    "Wallet projection version must be a positive safe integer"
+  );
+  if (projection.lastTransactionId !== void 0) {
+    assertEconomyIdentifier(
+      projection.lastTransactionId,
+      "lastTransactionId"
+    );
+  }
+  parseIsoTimestamp(projection.asOf);
+}
+function assertWalletBalanceDelta(delta) {
+  economyAssert(
+    delta.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet-balance-delta contract version"
+  );
+  assertEconomyIdentifier(delta.walletId, "walletId");
+  const values = [
+    parseTokenSubunits(delta.spendableDelta),
+    parseTokenSubunits(delta.reservedDelta),
+    parseTokenSubunits(delta.heldDelta)
+  ];
+  economyAssert(
+    values.some((value) => value !== 0n),
+    "INVALID_AMOUNT",
+    "Wallet balance delta must change at least one bucket"
+  );
+}
+function assertWalletBalanceDeltaBatch(transactionId, deltas) {
+  assertEconomyIdentifier(transactionId, "transactionId");
+  economyAssert(
+    deltas.length > 0,
+    "INVALID_CONTRACT",
+    "An economic transaction must update at least one wallet projection"
+  );
+  const walletIds = /* @__PURE__ */ new Set();
+  for (const delta of deltas) {
+    assertWalletBalanceDelta(delta);
+    economyAssert(
+      !walletIds.has(delta.walletId),
+      "DUPLICATE_IDENTIFIER",
+      "A balance-delta batch must update each wallet once"
+    );
+    walletIds.add(delta.walletId);
+  }
+}
+function applyWalletBalanceDelta(projection, delta, transactionId, asOf) {
+  assertWalletBalanceProjection(projection);
+  assertWalletBalanceDelta(delta);
+  assertEconomyIdentifier(transactionId, "transactionId");
+  economyAssert(
+    projection.walletId === delta.walletId,
+    "INVALID_CONTRACT",
+    "Wallet balance delta must target its projection wallet"
+  );
+  economyAssert(
+    parseIsoTimestamp(asOf) >= parseIsoTimestamp(projection.asOf),
+    "INVALID_TIME_WINDOW",
+    "Wallet balance update cannot precede its projection"
+  );
+  const next = {
+    ...projection,
+    spendable: serializeTokenSubunits(
+      parseTokenSubunits(projection.spendable) + parseTokenSubunits(delta.spendableDelta)
+    ),
+    reserved: serializeTokenSubunits(
+      parseTokenSubunits(projection.reserved) + parseTokenSubunits(delta.reservedDelta)
+    ),
+    held: serializeTokenSubunits(
+      parseTokenSubunits(projection.held) + parseTokenSubunits(delta.heldDelta)
+    ),
+    version: projection.version + 1,
+    lastTransactionId: transactionId,
+    asOf
+  };
+  assertWalletBalanceProjection(next);
+  return next;
+}
+function createWalletBalanceSummary(projection) {
+  assertWalletBalanceProjection(projection);
+  const spendable = parseTokenSubunits(projection.spendable);
+  const rewardProgress = spendable % 1000n;
+  const summary = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    walletId: projection.walletId,
+    available: serializeTokenSubunits(spendable - rewardProgress),
+    reserved: projection.reserved,
+    held: projection.held,
+    rewardProgress: serializeTokenSubunits(rewardProgress),
+    version: projection.version,
+    asOf: projection.asOf
+  };
+  assertDeterministicWalletBalanceSummary(summary);
+  return summary;
+}
+function assertDeterministicWalletBalanceSummary(summary) {
+  assertWalletBalanceSummary(summary);
+  economyAssert(
+    parseTokenSubunits(summary.available) % 1000n === 0n && parseTokenSubunits(summary.rewardProgress) < 1000n,
+    "INVALID_CONTRACT",
+    "Per-wallet availability must be whole Tokens with sub-Token progress below one Token"
+  );
+}
+function deriveWalletBalanceDeltas(transaction, bindings) {
+  assertEconomicJournalTransaction(transaction);
+  const byAccount = /* @__PURE__ */ new Map();
+  for (const binding of bindings) {
+    assertEconomyIdentifier(binding.accountId, "accountId");
+    assertEconomyIdentifier(binding.walletId, "walletId");
+    economyAssert(
+      ["spendable", "reserved", "held"].includes(binding.bucket),
+      "INVALID_CONTRACT",
+      "Wallet account binding has an unsupported bucket"
+    );
+    economyAssert(
+      !byAccount.has(binding.accountId),
+      "DUPLICATE_IDENTIFIER",
+      "A ledger account may bind to only one wallet bucket"
+    );
+    byAccount.set(binding.accountId, binding);
+  }
+  const byWallet = /* @__PURE__ */ new Map();
+  for (const posting of transaction.postings) {
+    if (posting.walletId === void 0) {
+      continue;
+    }
+    const binding = byAccount.get(posting.accountId);
+    economyAssert(
+      binding !== void 0 && binding.walletId === posting.walletId,
+      "INVALID_CONTRACT",
+      "Every wallet-linked posting must match an authoritative account binding"
+    );
+    const values = byWallet.get(binding.walletId) ?? [0n, 0n, 0n];
+    const amount = parseTokenSubunits(posting.amount);
+    if (binding.bucket === "spendable") {
+      values[0] += amount;
+    } else if (binding.bucket === "reserved") {
+      values[1] += amount;
+    } else {
+      values[2] += amount;
+    }
+    byWallet.set(binding.walletId, values);
+  }
+  const deltas = [...byWallet.entries()].map(([walletId, values]) => ({
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    walletId,
+    spendableDelta: serializeTokenSubunits(values[0]),
+    reservedDelta: serializeTokenSubunits(values[1]),
+    heldDelta: serializeTokenSubunits(values[2])
+  })).filter(
+    (delta) => delta.spendableDelta !== "0" || delta.reservedDelta !== "0" || delta.heldDelta !== "0"
+  ).sort((left, right) => left.walletId.localeCompare(right.walletId));
+  assertWalletBalanceDeltaBatch(transaction.transactionId, deltas);
+  return deltas;
+}
+var EARNED_ACTIVITY_TYPES = /* @__PURE__ */ new Set([
+  "rewarded-ad",
+  "offerwall",
+  "event",
+  "competition"
+]);
+function deriveWalletLifetimeDeltas(transaction) {
+  assertEconomicJournalTransaction(transaction);
+  if (transaction.status !== "settled") {
+    return [];
+  }
+  const netByWallet = /* @__PURE__ */ new Map();
+  for (const posting of transaction.postings) {
+    if (posting.walletId !== void 0) {
+      netByWallet.set(
+        posting.walletId,
+        (netByWallet.get(posting.walletId) ?? 0n) + parseTokenSubunits(posting.amount)
+      );
+    }
+  }
+  const deltas = [];
+  for (const [walletId, net] of [...netByWallet.entries()].sort(
+    ([left], [right]) => left.localeCompare(right)
+  )) {
+    let bucket;
+    let amount = 0n;
+    if (net > 0n && (transaction.activityType === "purchase" || transaction.activityType === "subscription")) {
+      bucket = "bought";
+      amount = net;
+    } else if (net > 0n && EARNED_ACTIVITY_TYPES.has(transaction.activityType)) {
+      bucket = "earned";
+      amount = net;
+    } else if (net < 0n && (transaction.activityType === "allocation" || transaction.activityType === "boost")) {
+      bucket = "allocated";
+      amount = -net;
+    } else if (net > 0n && transaction.activityType === "reclaim") {
+      bucket = "reclaimed";
+      amount = net;
+    } else if (net < 0n && transaction.activityType === "spend") {
+      bucket = "spent";
+      amount = -net;
+    } else if (net < 0n && (transaction.activityType === "refund" || transaction.activityType === "chargeback" || transaction.activityType === "reversal")) {
+      bucket = "reversed";
+      amount = -net;
+    }
+    if (bucket !== void 0) {
+      deltas.push({
+        schemaVersion: ECONOMY_CONTRACT_VERSION,
+        walletId,
+        bucket,
+        amount: serializeTokenSubunits(amount)
+      });
+    }
+  }
+  return deltas;
+}
+function applyWalletLifetimeDeltas(current, walletId, deltas) {
+  assertWalletLifetimeTotals(current);
+  assertEconomyIdentifier(walletId, "walletId");
+  const next = {
+    bought: parseTokenSubunits(current.bought),
+    earned: parseTokenSubunits(current.earned),
+    allocated: parseTokenSubunits(current.allocated),
+    reclaimed: parseTokenSubunits(current.reclaimed),
+    spent: parseTokenSubunits(current.spent),
+    reversed: parseTokenSubunits(current.reversed)
+  };
+  for (const delta of deltas) {
+    economyAssert(
+      delta.schemaVersion === ECONOMY_CONTRACT_VERSION && delta.walletId === walletId && [
+        "bought",
+        "earned",
+        "allocated",
+        "reclaimed",
+        "spent",
+        "reversed"
+      ].includes(delta.bucket),
+      "INVALID_CONTRACT",
+      "Lifetime delta must target the requested wallet and a known bucket"
+    );
+    const amount = parseTokenSubunits(delta.amount);
+    economyAssert(
+      amount > 0n,
+      "INVALID_AMOUNT",
+      "Lifetime deltas must be positive"
+    );
+    next[delta.bucket] += amount;
+  }
+  const totals = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    bought: serializeTokenSubunits(next.bought),
+    earned: serializeTokenSubunits(next.earned),
+    allocated: serializeTokenSubunits(next.allocated),
+    reclaimed: serializeTokenSubunits(next.reclaimed),
+    spent: serializeTokenSubunits(next.spent),
+    reversed: serializeTokenSubunits(next.reversed)
+  };
+  assertWalletLifetimeTotals(totals);
+  return totals;
+}
+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/ports/query.ts
+var ACTIVITY_TYPES2 = /* @__PURE__ */ new Set([
+  "purchase",
+  "subscription",
+  "rewarded-ad",
+  "offerwall",
+  "allocation",
+  "boost",
+  "reclaim",
+  "spend",
+  "hold",
+  "refund",
+  "chargeback",
+  "adjustment",
+  "reversal",
+  "event",
+  "competition"
+]);
+var ACTIVITY_STATUSES2 = /* @__PURE__ */ new Set([
+  "pending",
+  "held",
+  "settled",
+  "reversed",
+  "failed"
+]);
+var ACTIVITY_SOURCES2 = /* @__PURE__ */ new Set([
+  "shopify",
+  "ayet",
+  "bitlabs",
+  "subscription",
+  "event",
+  "competition",
+  "adjustment"
+]);
+var PORTFOLIO_ROLES = /* @__PURE__ */ new Set([
+  "household-treasury",
+  "personal",
+  "gameplay-allocation",
+  "hold"
+]);
+function hasControlCharacters2(value) {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31 || code === 127;
+  });
+}
+function assertSafeDisplayString(value, label) {
+  economyAssert(
+    typeof value === "string" && value.trim().length > 0 && value.length <= 128 && !hasControlCharacters2(value),
+    "INVALID_CONTRACT",
+    `${label} must be bounded and safe for display`
+  );
+}
+function assertOpaqueCursor(value) {
+  economyAssert(
+    typeof value === "string" && value.length > 0 && value.length <= 512 && !hasControlCharacters2(value),
+    "INVALID_CONTRACT",
+    "Activity cursor must be a bounded opaque value"
+  );
+}
+function assertUniqueValues(values, allowed, label) {
+  const unique = new Set(values);
+  economyAssert(
+    values.length > 0 && values.length === unique.size && values.every((value) => allowed.has(value)),
+    "INVALID_CONTRACT",
+    `${label} must contain unique supported values`
+  );
+}
+function assertWalletPortfolioReadScope(scope) {
+  economyAssert(
+    scope.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet-portfolio scope contract version"
+  );
+  assertEconomyIdentifier(scope.portfolioId, "portfolioId");
+  assertEconomyIdentifier(scope.subjectAccountId, "subjectAccountId");
+  economyAssert(
+    scope.components.length > 0 && scope.components.length <= 100,
+    "INVALID_CONTRACT",
+    "Wallet portfolio must contain between one and 100 components"
+  );
+  const walletIds = /* @__PURE__ */ new Set();
+  for (const component of scope.components) {
+    assertEconomyIdentifier(component.walletId, "walletId");
+    economyAssert(
+      PORTFOLIO_ROLES.has(component.role),
+      "INVALID_CONTRACT",
+      "Wallet portfolio component has an unsupported role"
+    );
+    economyAssert(
+      !walletIds.has(component.walletId),
+      "DUPLICATE_IDENTIFIER",
+      "Wallet portfolio cannot repeat a wallet"
+    );
+    walletIds.add(component.walletId);
+    if (component.beneficiaryAccountId !== void 0) {
+      assertEconomyIdentifier(
+        component.beneficiaryAccountId,
+        "beneficiaryAccountId"
+      );
+    }
+    economyAssert(
+      component.role !== "gameplay-allocation" || component.beneficiaryAccountId !== void 0,
+      "INVALID_CONTRACT",
+      "Gameplay-allocation portfolio components require a beneficiary"
+    );
+  }
+}
+function assertWalletLifetimeSnapshot(snapshot) {
+  economyAssert(
+    snapshot.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet-lifetime-snapshot contract version"
+  );
+  assertEconomyIdentifier(snapshot.walletId, "walletId");
+  assertWalletLifetimeTotals(snapshot.totals);
+  economyAssert(
+    Number.isSafeInteger(snapshot.version) && snapshot.version >= 1,
+    "INVALID_CONTRACT",
+    "Wallet lifetime version must be a positive safe integer"
+  );
+  parseIsoTimestamp(snapshot.asOf);
+}
+function assertPortfolioComponentMatch(expected, actual) {
+  economyAssert(
+    expected.walletId === actual.walletId && expected.role === actual.role && expected.beneficiaryAccountId === actual.beneficiaryAccountId,
+    "INVALID_CONTRACT",
+    "Portfolio result component does not match its authorized read scope"
+  );
+}
+function createWalletPortfolioSummary(scope, components, asOf) {
+  assertWalletPortfolioReadScope(scope);
+  parseIsoTimestamp(asOf);
+  economyAssert(
+    components.length === scope.components.length,
+    "INVALID_CONTRACT",
+    "Portfolio balance must include every authorized component exactly once"
+  );
+  const byWallet = new Map(components.map((item) => [item.walletId, item]));
+  economyAssert(
+    byWallet.size === components.length,
+    "DUPLICATE_IDENTIFIER",
+    "Portfolio balance cannot repeat a wallet"
+  );
+  const ordered = scope.components.map((expected) => {
+    const actual = byWallet.get(expected.walletId);
+    economyAssert(
+      actual !== void 0,
+      "INVALID_CONTRACT",
+      "Portfolio balance is missing an authorized wallet"
+    );
+    assertPortfolioComponentMatch(expected, actual);
+    assertDeterministicWalletBalanceSummary(actual.summary);
+    economyAssert(
+      actual.summary.walletId === actual.walletId && actual.summary.asOf === asOf,
+      "INVALID_CONTRACT",
+      "Portfolio component summary must identify its wallet and shared snapshot time"
+    );
+    return actual;
+  });
+  const totals = {
+    available: serializeTokenSubunits(
+      ordered.reduce(
+        (sum, item) => sum + parseTokenSubunits(item.summary.available),
+        0n
+      )
+    ),
+    reserved: serializeTokenSubunits(
+      ordered.reduce(
+        (sum, item) => sum + parseTokenSubunits(item.summary.reserved),
+        0n
+      )
+    ),
+    held: serializeTokenSubunits(
+      ordered.reduce(
+        (sum, item) => sum + parseTokenSubunits(item.summary.held),
+        0n
+      )
+    ),
+    rewardProgress: serializeTokenSubunits(
+      ordered.reduce(
+        (sum, item) => sum + parseTokenSubunits(item.summary.rewardProgress),
+        0n
+      )
+    )
+  };
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    portfolioId: scope.portfolioId,
+    subjectAccountId: scope.subjectAccountId,
+    components: ordered,
+    totals,
+    asOf
+  };
+}
+function assertWalletPortfolioSummary(summary) {
+  const scope = {
+    schemaVersion: summary.schemaVersion,
+    portfolioId: summary.portfolioId,
+    subjectAccountId: summary.subjectAccountId,
+    components: summary.components.map(
+      ({ walletId, role, beneficiaryAccountId }) => ({
+        walletId,
+        role,
+        ...beneficiaryAccountId === void 0 ? {} : { beneficiaryAccountId }
+      })
+    )
+  };
+  const rebuilt = createWalletPortfolioSummary(
+    scope,
+    summary.components,
+    summary.asOf
+  );
+  for (const field of [
+    "available",
+    "reserved",
+    "held",
+    "rewardProgress"
+  ]) {
+    economyAssert(
+      summary.totals[field] === rebuilt.totals[field],
+      "INVALID_CONTRACT",
+      "Portfolio balance totals must equal their component column sums"
+    );
+  }
+}
+function createWalletPortfolioLifetime(scope, components, asOf) {
+  assertWalletPortfolioReadScope(scope);
+  parseIsoTimestamp(asOf);
+  economyAssert(
+    components.length === scope.components.length,
+    "INVALID_CONTRACT",
+    "Portfolio lifetime must include every authorized component exactly once"
+  );
+  const byWallet = new Map(components.map((item) => [item.walletId, item]));
+  economyAssert(
+    byWallet.size === components.length,
+    "DUPLICATE_IDENTIFIER",
+    "Portfolio lifetime cannot repeat a wallet"
+  );
+  const ordered = scope.components.map((expected) => {
+    const actual = byWallet.get(expected.walletId);
+    economyAssert(
+      actual !== void 0,
+      "INVALID_CONTRACT",
+      "Portfolio lifetime is missing an authorized wallet"
+    );
+    assertPortfolioComponentMatch(expected, actual);
+    assertWalletLifetimeSnapshot(actual.snapshot);
+    economyAssert(
+      actual.snapshot.walletId === actual.walletId && actual.snapshot.asOf === asOf,
+      "INVALID_CONTRACT",
+      "Portfolio lifetime component must identify its wallet and shared snapshot time"
+    );
+    return actual;
+  });
+  const sumField = (field) => serializeTokenSubunits(
+    ordered.reduce(
+      (sum, item) => sum + parseTokenSubunits(item.snapshot.totals[field]),
+      0n
+    )
+  );
+  const totals = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    bought: sumField("bought"),
+    earned: sumField("earned"),
+    allocated: sumField("allocated"),
+    reclaimed: sumField("reclaimed"),
+    spent: sumField("spent"),
+    reversed: sumField("reversed")
+  };
+  assertWalletLifetimeTotals(totals);
+  return {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    portfolioId: scope.portfolioId,
+    subjectAccountId: scope.subjectAccountId,
+    components: ordered,
+    totals,
+    asOf
+  };
+}
+function assertWalletPortfolioLifetime(lifetime) {
+  const scope = {
+    schemaVersion: lifetime.schemaVersion,
+    portfolioId: lifetime.portfolioId,
+    subjectAccountId: lifetime.subjectAccountId,
+    components: lifetime.components.map(
+      ({ walletId, role, beneficiaryAccountId }) => ({
+        walletId,
+        role,
+        ...beneficiaryAccountId === void 0 ? {} : { beneficiaryAccountId }
+      })
+    )
+  };
+  const rebuilt = createWalletPortfolioLifetime(
+    scope,
+    lifetime.components,
+    lifetime.asOf
+  );
+  for (const field of [
+    "bought",
+    "earned",
+    "allocated",
+    "reclaimed",
+    "spent",
+    "reversed"
+  ]) {
+    economyAssert(
+      lifetime.totals[field] === rebuilt.totals[field],
+      "INVALID_CONTRACT",
+      "Portfolio lifetime totals must equal their component column sums"
+    );
+  }
+}
+function assertWalletActivityEntry(entry) {
+  economyAssert(
+    entry.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet-activity contract version"
+  );
+  assertEconomyIdentifier(entry.activityId, "activityId");
+  assertEconomyIdentifier(entry.walletId, "walletId");
+  economyAssert(
+    ACTIVITY_TYPES2.has(entry.activityType) && ACTIVITY_STATUSES2.has(entry.status) && ACTIVITY_SOURCES2.has(entry.source),
+    "INVALID_CONTRACT",
+    "Wallet activity type, status, or source is unsupported"
+  );
+  parseIsoTimestamp(entry.occurredAt);
+  economyAssert(
+    parseTokenSubunits(entry.amount) !== 0n,
+    "INVALID_AMOUNT",
+    "Wallet activity amount cannot be zero"
+  );
+  if (entry.beneficiaryAccountId !== void 0) {
+    assertEconomyIdentifier(
+      entry.beneficiaryAccountId,
+      "beneficiaryAccountId"
+    );
+  }
+  if (entry.maskedReference !== void 0) {
+    assertSafeDisplayString(entry.maskedReference, "Masked reference");
+  }
+  assertSafeDisplayString(entry.sourceLabel, "Source label");
+  economyAssert(
+    entry.entryKind === "economic" || entry.entryKind === "workflow",
+    "INVALID_CONTRACT",
+    "Wallet activity has an unsupported entry kind"
+  );
+  if (entry.entryKind === "economic") {
+    assertEconomyIdentifier(entry.transactionId, "transactionId");
+    economyAssert(
+      entry.status === "held" || entry.status === "settled" || entry.status === "reversed",
+      "INVALID_CONTRACT",
+      "Economic activity cannot use a workflow status"
+    );
+  } else {
+    assertEconomyIdentifier(entry.commandId, "commandId");
+    economyAssert(
+      entry.status === "pending" || entry.status === "failed",
+      "INVALID_CONTRACT",
+      "Workflow activity cannot use an economic status"
+    );
+  }
+}
+function assertWalletActivityPageRequest(request) {
+  economyAssert(
+    Number.isSafeInteger(request.limit) && request.limit >= 1 && request.limit <= 100,
+    "INVALID_CONTRACT",
+    "Activity page limit must be between one and 100"
+  );
+  if (request.cursor !== void 0) {
+    assertOpaqueCursor(request.cursor);
+  }
+  const filter = request.filter;
+  if (filter === void 0) {
+    return;
+  }
+  if (filter.activityTypes !== void 0) {
+    assertUniqueValues(filter.activityTypes, ACTIVITY_TYPES2, "Activity types");
+  }
+  if (filter.statuses !== void 0) {
+    assertUniqueValues(filter.statuses, ACTIVITY_STATUSES2, "Activity statuses");
+  }
+  if (filter.sources !== void 0) {
+    assertUniqueValues(filter.sources, ACTIVITY_SOURCES2, "Activity sources");
+  }
+  if (filter.beneficiaryAccountId !== void 0) {
+    assertEconomyIdentifier(
+      filter.beneficiaryAccountId,
+      "beneficiaryAccountId"
+    );
+  }
+  const from = filter.fromInclusive === void 0 ? void 0 : parseIsoTimestamp(filter.fromInclusive);
+  const to = filter.toExclusive === void 0 ? void 0 : parseIsoTimestamp(filter.toExclusive);
+  economyAssert(
+    from === void 0 || to === void 0 || from < to,
+    "INVALID_TIME_WINDOW",
+    "Activity filter start must precede its exclusive end"
+  );
+}
+function assertWalletActivityPage(page) {
+  economyAssert(
+    page.schemaVersion === ECONOMY_CONTRACT_VERSION && typeof page.hasMore === "boolean",
+    "INVALID_CONTRACT",
+    "Unsupported wallet-activity-page contract"
+  );
+  economyAssert(
+    page.hasMore === (page.nextCursor !== void 0),
+    "INVALID_CONTRACT",
+    "Activity page cursor must be present exactly when more rows exist"
+  );
+  economyAssert(
+    page.entries.length <= 100 && (!page.hasMore || page.entries.length > 0),
+    "INVALID_CONTRACT",
+    "Activity pages are bounded and cannot advertise more rows from an empty page"
+  );
+  if (page.nextCursor !== void 0) {
+    assertOpaqueCursor(page.nextCursor);
+  }
+  const activityIds = /* @__PURE__ */ new Set();
+  let previous;
+  for (const entry of page.entries) {
+    assertWalletActivityEntry(entry);
+    economyAssert(
+      !activityIds.has(entry.activityId),
+      "DUPLICATE_IDENTIFIER",
+      "Activity page cannot repeat an activity ID"
+    );
+    activityIds.add(entry.activityId);
+    if (previous !== void 0) {
+      const previousTime = parseIsoTimestamp(previous.occurredAt);
+      const currentTime = parseIsoTimestamp(entry.occurredAt);
+      economyAssert(
+        previousTime > currentTime || previousTime === currentTime && previous.activityId.localeCompare(entry.activityId) > 0,
+        "INVALID_CONTRACT",
+        "Activity page must use stable descending time and ID order"
+      );
+    }
+    previous = entry;
+  }
+}
+function assertWalletActivityPageForPortfolio(page, scope) {
+  assertWalletActivityPage(page);
+  assertWalletPortfolioReadScope(scope);
+  const walletIds = new Set(scope.components.map((item) => item.walletId));
+  economyAssert(
+    page.entries.every((entry) => walletIds.has(entry.walletId)),
+    "INVALID_CONTRACT",
+    "Portfolio activity contains a wallet outside its authorized read scope"
+  );
+}
+
+// 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"
+    );
+  }
+}
 export {
   BASELINE_GBP_CATALOG_VERSION,
   BASELINE_GBP_REFERENCE_RATE,
   BASELINE_GBP_TOKEN_PACKS,
   BASELINE_MONTHLY_SUBSCRIPTION_PLAN,
   BASELINE_PURCHASE_LIMIT_POLICY,
+  EARLY_BACKER_SETTLEMENT_POLICY_V2,
   ECONOMY_CONTRACT_VERSION,
   EconomyError,
   PRE_UTILITY_BACKER_COHORT,
   TOKEN_SUBUNITS_MAX,
   TOKEN_SUBUNITS_MIN,
   TOKEN_SUBUNITS_PER_TOKEN,
+  advanceJournalChainHead,
+  applySourceLotMovement,
   applyTransactionToProjection,
+  applyWalletBalanceDelta,
+  applyWalletLifetimeDeltas,
   assertActivityEntry,
   assertBalancedTransaction,
+  assertDeterministicWalletBalanceSummary,
   assertDistinctAdjustmentApproval,
+  assertEconomicJournalTransaction,
+  assertEconomyCommandEnvelope,
+  assertEconomyCommandWorkflowEvent,
+  assertEconomyIdempotencyScope,
   assertEconomyIdentifier,
   assertFlatTokenCatalog,
   assertFxSnapshot,
   assertGameplayAllocation,
+  assertJournalChainHead,
   assertNonNegativeAccounts,
   assertOpenPurchaseIntent,
   assertPurchaseIntentBinding,
@@ -1607,24 +2820,46 @@ export {
   assertReversalAvailable,
   assertRewardConversion,
   assertRewardRate,
+  assertScopedPersistedIdempotencyResult,
   assertSourceLot,
+  assertSourceLotMovement,
   assertSpendRequest,
   assertTokenPack,
   assertTokenReferenceRate,
   assertTokenSubscriptionPlan,
+  assertVersionedSourceLot,
   assertWallet,
+  assertWalletActivityEntry,
+  assertWalletActivityPage,
+  assertWalletActivityPageForPortfolio,
+  assertWalletActivityPageRequest,
+  assertWalletBalanceDelta,
+  assertWalletBalanceDeltaBatch,
+  assertWalletBalanceProjection,
   assertWalletBalanceSummary,
+  assertWalletLifetimeSnapshot,
   assertWalletLifetimeTotals,
+  assertWalletOwnerReference,
+  assertWalletPortfolioLifetime,
+  assertWalletPortfolioReadScope,
+  assertWalletPortfolioSummary,
   availableSourceLotAmount,
   boostGameplayAllocation,
   canUseSourceLot,
   canonicalTransactionPayload,
   convertRewardPayout,
   createGameplayAllocation,
+  createInitialSourceLotSnapshot,
   createProjectionSnapshot,
   createReversalTransaction,
+  createWalletBalanceSummary,
+  createWalletPortfolioLifetime,
+  createWalletPortfolioSummary,
+  deriveWalletBalanceDeltas,
+  deriveWalletLifetimeDeltas,
   economyAssert,
   evaluateEarlyBacker,
+  evaluateEarlyBackerBySettlementV2,
   isWholeTokenAmount,
   mapBitLabsConversionState,
   parseIsoTimestamp,