@plasius/economy 0.5.0 → 0.6.0

package/README.md

@@ -399,6 +399,21 @@ across wallets, even if the sum reaches 1,000 TokenSubunits, because source and
 transfer restrictions may differ. Authorization must happen before the server
 constructs a portfolio scope.
 
+`createPersonalWalletInitializationState()` supplies the exact baseline needed
+before a self account can read a portfolio: deterministic document IDs, one
+account-owned personal `WalletV1`, a single-component scope, exact-zero balance
+and lifetime projections, no activity entries, and a privacy-minimized
+`wallet.initialized.v1` outbox intent. The caller provides SHA-256 and must
+commit the state with audited receipts, idempotency, the authority manifest and
+conditional head advance in one ACID boundary.
+
+`initialize-wallet` exists only in `EconomyAuditedCommandTypeV1`; legacy V1/V2
+command unions remain unchanged. It accepts a direct self-account browser
+principal only and terminates with `WALLET_INITIALIZED` or
+`WALLET_ALREADY_INITIALIZED` as a no-economic result. It never creates a
+double-entry transaction or Token activity row and does not authorize value or
+provider writes.
+
 Activity reads use bounded opaque cursor pagination in stable descending
 `(occurredAt, activityId)` order. Each row retains the component `walletId`
 whose signed display amount it represents. Cursor contents and signatures are

package/dist/index.cjs

@@ -103,6 +103,9 @@ __export(index_exports, {
   assertPaidLotLifecycle: () => assertPaidLotLifecycle,
   assertPaidLotLifecycleEvent: () => assertPaidLotLifecycleEvent,
   assertPaidLotPurchaseProvenance: () => assertPaidLotPurchaseProvenance,
+  assertPersonalWalletInitializationCommand: () => assertPersonalWalletInitializationCommand,
+  assertPersonalWalletInitializationOutboxIntent: () => assertPersonalWalletInitializationOutboxIntent,
+  assertPersonalWalletInitializationState: () => assertPersonalWalletInitializationState,
   assertPurchaseCapReservation: () => assertPurchaseCapReservation,
   assertPurchaseCapReservationTransition: () => assertPurchaseCapReservationTransition,
   assertPurchaseIntentBinding: () => assertPurchaseIntentBinding,
@@ -160,6 +163,8 @@ __export(index_exports, {
   canonicalEconomyRegionalEvidenceReceiptBodyPayload: () => canonicalEconomyRegionalEvidenceReceiptBodyPayload,
   canonicalEconomyRegionalEvidenceReceiptPayload: () => canonicalEconomyRegionalEvidenceReceiptPayload,
   canonicalEconomyRegionalEvidenceReceiptSigningPayload: () => canonicalEconomyRegionalEvidenceReceiptSigningPayload,
+  canonicalPersonalWalletInitializationCommandPayload: () => canonicalPersonalWalletInitializationCommandPayload,
+  canonicalPersonalWalletInitializationOutboxPayload: () => canonicalPersonalWalletInitializationOutboxPayload,
   canonicalTransactionPayload: () => canonicalTransactionPayload,
   closeModuleAllowance: () => closeModuleAllowance,
   convertRewardPayout: () => convertRewardPayout,
@@ -175,6 +180,8 @@ __export(index_exports, {
   createModuleSpendHold: () => createModuleSpendHold,
   createModuleSpendQuote: () => createModuleSpendQuote,
   createPaidLotLifecycle: () => createPaidLotLifecycle,
+  createPersonalWalletInitializationDocumentIds: () => createPersonalWalletInitializationDocumentIds,
+  createPersonalWalletInitializationState: () => createPersonalWalletInitializationState,
   createProjectionSnapshot: () => createProjectionSnapshot,
   createPurchaseIntentLifecycle: () => createPurchaseIntentLifecycle,
   createReversalTransaction: () => createReversalTransaction,
@@ -965,7 +972,8 @@ var COMMAND_TYPES = /* @__PURE__ */ new Set([
   "refund",
   "chargeback",
   "reverse",
-  "adjust"
+  "adjust",
+  "initialize-wallet"
 ]);
 var COMMAND_SOURCES = /* @__PURE__ */ new Set([
   "browser",
@@ -1012,7 +1020,8 @@ var SOURCE_COMMAND_TYPES = {
     "reclaim",
     "spend",
     "hold",
-    "release-hold"
+    "release-hold",
+    "initialize-wallet"
   ]),
   shopify: /* @__PURE__ */ new Set([
     "credit-purchase",
@@ -1207,6 +1216,13 @@ function assertCommandSourcePrincipal(envelope) {
       "Delegated-child commands require a distinct actor and relationship"
     );
   }
+  if (envelope.commandType === "initialize-wallet") {
+    economyAssert(
+      envelope.commandSource === "browser" && envelope.principalType === "account" && envelope.actorAccountId === envelope.subjectAccountId && envelope.relationshipId === void 0 && envelope.authorizationVersion === void 0,
+      "INVALID_CONTRACT",
+      "Wallet initialization requires a direct self-account browser command"
+    );
+  }
 }
 function assertAuditedEconomyCommandEnvelope(envelope) {
   assertExactKeys(
@@ -1808,6 +1824,7 @@ var RECORD_KINDS = /* @__PURE__ */ new Set([
   "source-lot",
   "source-lot-movement",
   "gameplay-allocation",
+  "wallet",
   "balance-projection",
   "lifetime-projection",
   "idempotency-result",
@@ -2995,6 +3012,13 @@ function assertReceiptGraph(graph, commandEnvelopeHash, hash, acceptanceCommit,
     result.receiptId,
     resultHash
   );
+  if (envelope.commandType === "initialize-wallet") {
+    economyAssert(
+      result.outcome === "no-op" && (result.noOpCode === "WALLET_INITIALIZED" || result.noOpCode === "WALLET_ALREADY_INITIALIZED"),
+      "INVALID_CONTRACT",
+      "Wallet initialization must terminate without an economic transaction"
+    );
+  }
   if (result.outcome !== "completed") {
     economyAssert(
       graph.transaction === void 0,
@@ -8331,6 +8355,241 @@ function assertSpendRequest(request) {
     );
   }
 }
+
+// src/wallet-initialization.ts
+var INITIALIZATION_IDENTITY_DOMAIN = "economy.personal-wallet-initialization.identity.v1";
+var ZERO_TOKEN_SUBUNITS = serializeTokenSubunits(0n);
+var STATE_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "documentIds",
+  "command",
+  "wallet",
+  "scope",
+  "balance",
+  "lifetime",
+  "activityEntries",
+  "outboxIntent"
+]);
+var COMMAND_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "commandType",
+  "walletKind",
+  "subjectAccountId",
+  "walletId",
+  "portfolioId",
+  "initializedAt"
+]);
+var OUTBOX_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "eventType",
+  "eventId",
+  "subjectAccountId",
+  "walletId",
+  "portfolioId",
+  "occurredAt"
+]);
+var DOCUMENT_ID_KEYS = /* @__PURE__ */ new Set([
+  "walletDescriptorId",
+  "accessProjectionId",
+  "balanceProjectionId",
+  "lifetimeProjectionId",
+  "outboxEventId"
+]);
+function assertExactKeys4(value, allowed, label) {
+  economyAssert(
+    value !== null && typeof value === "object" && !Array.isArray(value),
+    "INVALID_CONTRACT",
+    `${label} must be an object`
+  );
+  economyAssert(
+    Object.keys(value).every((key) => allowed.has(key)),
+    "INVALID_CONTRACT",
+    `${label} contains an unsupported field`
+  );
+}
+function identityDigest(subjectAccountId, hash) {
+  assertEconomyIdentifier(subjectAccountId, "subjectAccountId");
+  const canonicalIdentity = JSON.stringify({
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    domain: INITIALIZATION_IDENTITY_DOMAIN,
+    subjectAccountId
+  });
+  const canonicalHash2 = hash(canonicalIdentity);
+  economyAssert(
+    /^sha256:[a-f0-9]{64}$/u.test(canonicalHash2),
+    "INVALID_CONTRACT",
+    "Wallet initialization identity hash must be canonical SHA-256"
+  );
+  return canonicalHash2.slice("sha256:".length);
+}
+function createPersonalWalletInitializationDocumentIds(subjectAccountId, hash) {
+  const digest = identityDigest(subjectAccountId, hash);
+  return {
+    walletId: `wallet:personal:${digest}`,
+    portfolioId: `portfolio:self:${digest}`,
+    walletDescriptorId: `wallet-descriptor:${digest}`,
+    accessProjectionId: `wallet-access:${digest}`,
+    balanceProjectionId: `wallet-balance:${digest}`,
+    lifetimeProjectionId: `wallet-lifetime:${digest}`,
+    outboxEventId: `outbox:wallet-initialized:${digest}`
+  };
+}
+function assertPersonalWalletInitializationCommand(command) {
+  assertExactKeys4(command, COMMAND_KEYS, "Wallet initialization command");
+  economyAssert(
+    command.schemaVersion === ECONOMY_CONTRACT_VERSION && command.commandType === "initialize-wallet" && command.walletKind === "personal",
+    "INVALID_CONTRACT",
+    "Unsupported personal-wallet initialization command"
+  );
+  assertEconomyIdentifier(command.subjectAccountId, "subjectAccountId");
+  assertEconomyIdentifier(command.walletId, "walletId");
+  assertEconomyIdentifier(command.portfolioId, "portfolioId");
+  parseIsoTimestamp(command.initializedAt);
+}
+function canonicalPersonalWalletInitializationCommandPayload(command) {
+  assertPersonalWalletInitializationCommand(command);
+  return JSON.stringify({
+    schemaVersion: command.schemaVersion,
+    commandType: command.commandType,
+    walletKind: command.walletKind,
+    subjectAccountId: command.subjectAccountId,
+    walletId: command.walletId,
+    portfolioId: command.portfolioId,
+    initializedAt: command.initializedAt
+  });
+}
+function assertPersonalWalletInitializationOutboxIntent(intent) {
+  assertExactKeys4(intent, OUTBOX_KEYS, "Wallet initialization outbox intent");
+  economyAssert(
+    intent.schemaVersion === ECONOMY_CONTRACT_VERSION && intent.eventType === "wallet.initialized.v1",
+    "INVALID_CONTRACT",
+    "Unsupported wallet initialization outbox intent"
+  );
+  assertEconomyIdentifier(intent.eventId, "eventId");
+  assertEconomyIdentifier(intent.subjectAccountId, "subjectAccountId");
+  assertEconomyIdentifier(intent.walletId, "walletId");
+  assertEconomyIdentifier(intent.portfolioId, "portfolioId");
+  parseIsoTimestamp(intent.occurredAt);
+}
+function canonicalPersonalWalletInitializationOutboxPayload(intent) {
+  assertPersonalWalletInitializationOutboxIntent(intent);
+  return JSON.stringify({
+    schemaVersion: intent.schemaVersion,
+    eventType: intent.eventType,
+    eventId: intent.eventId,
+    subjectAccountId: intent.subjectAccountId,
+    walletId: intent.walletId,
+    portfolioId: intent.portfolioId,
+    occurredAt: intent.occurredAt
+  });
+}
+function createPersonalWalletInitializationState(input, hash) {
+  parseIsoTimestamp(input.initializedAt);
+  const { walletId, portfolioId, ...documentIds } = createPersonalWalletInitializationDocumentIds(
+    input.subjectAccountId,
+    hash
+  );
+  const command = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    commandType: "initialize-wallet",
+    walletKind: "personal",
+    subjectAccountId: input.subjectAccountId,
+    walletId,
+    portfolioId,
+    initializedAt: input.initializedAt
+  };
+  const state = {
+    schemaVersion: ECONOMY_CONTRACT_VERSION,
+    documentIds,
+    command,
+    wallet: {
+      schemaVersion: ECONOMY_CONTRACT_VERSION,
+      walletId,
+      accountId: input.subjectAccountId,
+      kind: "personal",
+      ownerType: "account",
+      ownerId: input.subjectAccountId,
+      status: "active",
+      version: 1,
+      createdAt: input.initializedAt
+    },
+    scope: {
+      schemaVersion: ECONOMY_CONTRACT_VERSION,
+      portfolioId,
+      subjectAccountId: input.subjectAccountId,
+      components: [{ walletId, role: "personal" }]
+    },
+    balance: {
+      schemaVersion: ECONOMY_CONTRACT_VERSION,
+      walletId,
+      available: ZERO_TOKEN_SUBUNITS,
+      reserved: ZERO_TOKEN_SUBUNITS,
+      held: ZERO_TOKEN_SUBUNITS,
+      rewardProgress: ZERO_TOKEN_SUBUNITS,
+      version: 1,
+      asOf: input.initializedAt
+    },
+    lifetime: {
+      schemaVersion: ECONOMY_CONTRACT_VERSION,
+      walletId,
+      totals: {
+        schemaVersion: ECONOMY_CONTRACT_VERSION,
+        bought: ZERO_TOKEN_SUBUNITS,
+        earned: ZERO_TOKEN_SUBUNITS,
+        allocated: ZERO_TOKEN_SUBUNITS,
+        reclaimed: ZERO_TOKEN_SUBUNITS,
+        spent: ZERO_TOKEN_SUBUNITS,
+        reversed: ZERO_TOKEN_SUBUNITS
+      },
+      version: 1,
+      asOf: input.initializedAt
+    },
+    activityEntries: [],
+    outboxIntent: {
+      schemaVersion: ECONOMY_CONTRACT_VERSION,
+      eventType: "wallet.initialized.v1",
+      eventId: documentIds.outboxEventId,
+      subjectAccountId: input.subjectAccountId,
+      walletId,
+      portfolioId,
+      occurredAt: input.initializedAt
+    }
+  };
+  assertPersonalWalletInitializationState(state);
+  return state;
+}
+function assertPersonalWalletInitializationState(state) {
+  assertExactKeys4(state, STATE_KEYS, "Wallet initialization state");
+  assertExactKeys4(
+    state.documentIds,
+    DOCUMENT_ID_KEYS,
+    "Wallet initialization document IDs"
+  );
+  economyAssert(
+    state.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported wallet initialization state"
+  );
+  for (const identifier of Object.values(state.documentIds)) {
+    assertEconomyIdentifier(identifier, "wallet initialization document ID");
+  }
+  economyAssert(
+    new Set(Object.values(state.documentIds)).size === Object.values(state.documentIds).length,
+    "INVALID_CONTRACT",
+    "Wallet initialization document IDs must be unique"
+  );
+  assertPersonalWalletInitializationCommand(state.command);
+  assertWallet(state.wallet);
+  assertWalletPortfolioReadScope(state.scope);
+  assertWalletBalanceSummary(state.balance);
+  assertWalletLifetimeSnapshot(state.lifetime);
+  assertPersonalWalletInitializationOutboxIntent(state.outboxIntent);
+  economyAssert(
+    state.wallet.walletId === state.command.walletId && state.wallet.accountId === state.command.subjectAccountId && state.wallet.ownerId === state.command.subjectAccountId && state.wallet.kind === "personal" && state.wallet.ownerType === "account" && state.wallet.createdAt === state.command.initializedAt && state.scope.portfolioId === state.command.portfolioId && state.scope.subjectAccountId === state.command.subjectAccountId && state.scope.components.length === 1 && state.scope.components[0]?.walletId === state.command.walletId && state.scope.components[0]?.role === "personal" && state.scope.components[0]?.beneficiaryAccountId === void 0 && state.balance.walletId === state.command.walletId && state.balance.available === ZERO_TOKEN_SUBUNITS && state.balance.reserved === ZERO_TOKEN_SUBUNITS && state.balance.held === ZERO_TOKEN_SUBUNITS && state.balance.rewardProgress === ZERO_TOKEN_SUBUNITS && state.balance.version === 1 && state.balance.asOf === state.command.initializedAt && state.lifetime.walletId === state.command.walletId && state.lifetime.version === 1 && state.lifetime.asOf === state.command.initializedAt && state.lifetime.totals.bought === ZERO_TOKEN_SUBUNITS && state.lifetime.totals.earned === ZERO_TOKEN_SUBUNITS && state.lifetime.totals.allocated === ZERO_TOKEN_SUBUNITS && state.lifetime.totals.reclaimed === ZERO_TOKEN_SUBUNITS && state.lifetime.totals.spent === ZERO_TOKEN_SUBUNITS && state.lifetime.totals.reversed === ZERO_TOKEN_SUBUNITS && state.activityEntries.length === 0 && state.outboxIntent.eventId === state.documentIds.outboxEventId && state.outboxIntent.subjectAccountId === state.command.subjectAccountId && state.outboxIntent.walletId === state.command.walletId && state.outboxIntent.portfolioId === state.command.portfolioId && state.outboxIntent.occurredAt === state.command.initializedAt,
+    "INVALID_CONTRACT",
+    "Personal-wallet initialization state is incomplete or inconsistent"
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BASELINE_GBP_CATALOG_VERSION,
@@ -8416,6 +8675,9 @@ function assertSpendRequest(request) {
   assertPaidLotLifecycle,
   assertPaidLotLifecycleEvent,
   assertPaidLotPurchaseProvenance,
+  assertPersonalWalletInitializationCommand,
+  assertPersonalWalletInitializationOutboxIntent,
+  assertPersonalWalletInitializationState,
   assertPurchaseCapReservation,
   assertPurchaseCapReservationTransition,
   assertPurchaseIntentBinding,
@@ -8473,6 +8735,8 @@ function assertSpendRequest(request) {
   canonicalEconomyRegionalEvidenceReceiptBodyPayload,
   canonicalEconomyRegionalEvidenceReceiptPayload,
   canonicalEconomyRegionalEvidenceReceiptSigningPayload,
+  canonicalPersonalWalletInitializationCommandPayload,
+  canonicalPersonalWalletInitializationOutboxPayload,
   canonicalTransactionPayload,
   closeModuleAllowance,
   convertRewardPayout,
@@ -8488,6 +8752,8 @@ function assertSpendRequest(request) {
   createModuleSpendHold,
   createModuleSpendQuote,
   createPaidLotLifecycle,
+  createPersonalWalletInitializationDocumentIds,
+  createPersonalWalletInitializationState,
   createProjectionSnapshot,
   createPurchaseIntentLifecycle,
   createReversalTransaction,