@plasius/economy 0.5.0 → 0.7.0

package/dist/index.js

@@ -745,7 +745,8 @@ var COMMAND_TYPES = /* @__PURE__ */ new Set([
   "refund",
   "chargeback",
   "reverse",
-  "adjust"
+  "adjust",
+  "initialize-wallet"
 ]);
 var COMMAND_SOURCES = /* @__PURE__ */ new Set([
   "browser",
@@ -792,7 +793,8 @@ var SOURCE_COMMAND_TYPES = {
     "reclaim",
     "spend",
     "hold",
-    "release-hold"
+    "release-hold",
+    "initialize-wallet"
   ]),
   shopify: /* @__PURE__ */ new Set([
     "credit-purchase",
@@ -987,6 +989,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(
@@ -1588,6 +1597,7 @@ var RECORD_KINDS = /* @__PURE__ */ new Set([
   "source-lot",
   "source-lot-movement",
   "gameplay-allocation",
+  "wallet",
   "balance-projection",
   "lifetime-projection",
   "idempotency-result",
@@ -2775,6 +2785,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,
@@ -4302,6 +4319,341 @@ function assertDistinctAdjustmentApproval(request) {
   }
 }
 
+// src/operator-adjustments.ts
+var PREVIEW_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "previewId",
+  "adjustmentId",
+  "operation",
+  "targetAccountId",
+  "targetComponent",
+  "targetWalletId",
+  "targetLedgerAccountId",
+  "offsetLedgerAccountId",
+  "sourceLotId",
+  "amount",
+  "reasonCode",
+  "ticketReferenceHash",
+  "transferPolicy",
+  "refundPolicy",
+  "originalSourceLotId",
+  "originalTransactionId",
+  "preparedAt",
+  "expiresAt"
+]);
+var DECISION_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "decisionId",
+  "adjustmentId",
+  "proposalId",
+  "proposalHash",
+  "previewHash",
+  "decision",
+  "proposedByAccountId",
+  "decidedByAccountId",
+  "proposedAt",
+  "decidedAt"
+]);
+var PROPOSAL_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "proposalId",
+  "adjustmentId",
+  "previewHash",
+  "status",
+  "proposedByAccountId",
+  "proposedAt",
+  "expiresAt"
+]);
+var EXECUTION_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "executionId",
+  "adjustmentId",
+  "previewHash",
+  "proposalHash",
+  "decisionHash",
+  "sourceLotId",
+  "transactionId",
+  "resultReceiptId",
+  "executedAt"
+]);
+var OPERATIONS = /* @__PURE__ */ new Set([
+  "credit",
+  "reverse-credit"
+]);
+var TARGET_COMPONENTS = /* @__PURE__ */ new Set([
+  "personal",
+  "household-treasury"
+]);
+var TRANSFER_POLICIES = /* @__PURE__ */ new Set([
+  "household-allocatable",
+  "same-user-only",
+  "non-transferable"
+]);
+var DECISIONS = /* @__PURE__ */ new Set([
+  "approve",
+  "reject"
+]);
+function assertExactKeys3(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 assertCanonicalHash6(value, label) {
+  economyAssert(
+    /^sha256:[a-f0-9]{64}$/u.test(value),
+    "INVALID_CONTRACT",
+    `${label} must be a canonical SHA-256 reference`
+  );
+}
+function assertReasonCode(reasonCode) {
+  economyAssert(
+    /^[A-Z][A-Z0-9_]{2,95}$/u.test(reasonCode),
+    "INVALID_CONTRACT",
+    "Adjustment reasonCode must be a bounded uppercase identifier"
+  );
+}
+function assertOperatorAdjustmentPreview(preview) {
+  assertExactKeys3(preview, PREVIEW_KEYS, "Operator adjustment preview");
+  economyAssert(
+    preview.schemaVersion === ECONOMY_CONTRACT_VERSION && OPERATIONS.has(preview.operation) && TARGET_COMPONENTS.has(preview.targetComponent) && TRANSFER_POLICIES.has(preview.transferPolicy) && preview.refundPolicy === "not-refundable",
+    "INVALID_CONTRACT",
+    "Unsupported operator adjustment preview"
+  );
+  assertEconomyIdentifier(preview.previewId, "previewId");
+  assertEconomyIdentifier(preview.adjustmentId, "adjustmentId");
+  assertEconomyIdentifier(preview.targetAccountId, "targetAccountId");
+  assertEconomyIdentifier(preview.targetWalletId, "targetWalletId");
+  assertEconomyIdentifier(
+    preview.targetLedgerAccountId,
+    "targetLedgerAccountId"
+  );
+  assertEconomyIdentifier(
+    preview.offsetLedgerAccountId,
+    "offsetLedgerAccountId"
+  );
+  assertEconomyIdentifier(preview.sourceLotId, "sourceLotId");
+  economyAssert(
+    parseTokenSubunits(preview.amount) > 0n,
+    "INVALID_AMOUNT",
+    "Operator adjustment amount must be positive"
+  );
+  assertReasonCode(preview.reasonCode);
+  assertCanonicalHash6(preview.ticketReferenceHash, "ticketReferenceHash");
+  const preparedAt = parseIsoTimestamp(preview.preparedAt);
+  const expiresAt = parseIsoTimestamp(preview.expiresAt);
+  economyAssert(
+    expiresAt > preparedAt,
+    "INVALID_TIME_WINDOW",
+    "Operator adjustment preview must expire after preparation"
+  );
+  if (preview.operation === "credit") {
+    economyAssert(
+      preview.originalSourceLotId === void 0 && preview.originalTransactionId === void 0,
+      "INVALID_CONTRACT",
+      "A credit preview cannot bind an original transaction"
+    );
+    return;
+  }
+  economyAssert(
+    preview.originalSourceLotId !== void 0 && preview.originalTransactionId !== void 0,
+    "INVALID_CONTRACT",
+    "A reversal preview must bind the original lot and transaction"
+  );
+  assertEconomyIdentifier(preview.originalSourceLotId, "originalSourceLotId");
+  assertEconomyIdentifier(
+    preview.originalTransactionId,
+    "originalTransactionId"
+  );
+}
+function canonicalOperatorAdjustmentPreviewPayload(preview) {
+  assertOperatorAdjustmentPreview(preview);
+  return JSON.stringify({
+    schemaVersion: preview.schemaVersion,
+    previewId: preview.previewId,
+    adjustmentId: preview.adjustmentId,
+    operation: preview.operation,
+    targetAccountId: preview.targetAccountId,
+    targetComponent: preview.targetComponent,
+    targetWalletId: preview.targetWalletId,
+    targetLedgerAccountId: preview.targetLedgerAccountId,
+    offsetLedgerAccountId: preview.offsetLedgerAccountId,
+    sourceLotId: preview.sourceLotId,
+    amount: preview.amount,
+    reasonCode: preview.reasonCode,
+    ticketReferenceHash: preview.ticketReferenceHash,
+    transferPolicy: preview.transferPolicy,
+    refundPolicy: preview.refundPolicy,
+    ...preview.originalSourceLotId === void 0 ? {} : { originalSourceLotId: preview.originalSourceLotId },
+    ...preview.originalTransactionId === void 0 ? {} : { originalTransactionId: preview.originalTransactionId },
+    preparedAt: preview.preparedAt,
+    expiresAt: preview.expiresAt
+  });
+}
+function assertOperatorAdjustmentProposal(proposal, preview, expectedPreviewHash) {
+  assertOperatorAdjustmentPreview(preview);
+  assertCanonicalHash6(expectedPreviewHash, "expectedPreviewHash");
+  assertExactKeys3(proposal, PROPOSAL_KEYS, "Operator adjustment proposal");
+  economyAssert(
+    proposal.schemaVersion === ECONOMY_CONTRACT_VERSION && proposal.status === "pending-approval",
+    "INVALID_CONTRACT",
+    "Unsupported operator adjustment proposal"
+  );
+  assertEconomyIdentifier(proposal.proposalId, "proposalId");
+  assertEconomyIdentifier(proposal.adjustmentId, "adjustmentId");
+  assertCanonicalHash6(proposal.previewHash, "previewHash");
+  assertEconomyIdentifier(
+    proposal.proposedByAccountId,
+    "proposedByAccountId"
+  );
+  economyAssert(
+    proposal.adjustmentId === preview.adjustmentId && proposal.previewHash === expectedPreviewHash,
+    "ADJUSTMENT_PREVIEW_MISMATCH",
+    "Operator adjustment proposal does not match its preview"
+  );
+  const proposedAt = parseIsoTimestamp(proposal.proposedAt);
+  const expiresAt = parseIsoTimestamp(proposal.expiresAt);
+  economyAssert(
+    proposedAt >= parseIsoTimestamp(preview.preparedAt) && expiresAt === parseIsoTimestamp(preview.expiresAt) && expiresAt > proposedAt,
+    "INVALID_TIME_WINDOW",
+    "Operator adjustment proposal times are inconsistent"
+  );
+}
+function canonicalOperatorAdjustmentProposalPayload(proposal) {
+  assertExactKeys3(proposal, PROPOSAL_KEYS, "Operator adjustment proposal");
+  return JSON.stringify({
+    schemaVersion: proposal.schemaVersion,
+    proposalId: proposal.proposalId,
+    adjustmentId: proposal.adjustmentId,
+    previewHash: proposal.previewHash,
+    status: proposal.status,
+    proposedByAccountId: proposal.proposedByAccountId,
+    proposedAt: proposal.proposedAt,
+    expiresAt: proposal.expiresAt
+  });
+}
+function assertOperatorAdjustmentDecision(decision, proposal, preview, expectedPreviewHash, expectedProposalHash) {
+  assertOperatorAdjustmentProposal(proposal, preview, expectedPreviewHash);
+  assertCanonicalHash6(expectedProposalHash, "expectedProposalHash");
+  assertExactKeys3(decision, DECISION_KEYS, "Operator adjustment decision");
+  economyAssert(
+    decision.schemaVersion === ECONOMY_CONTRACT_VERSION && DECISIONS.has(decision.decision),
+    "INVALID_CONTRACT",
+    "Unsupported operator adjustment decision"
+  );
+  assertEconomyIdentifier(decision.decisionId, "decisionId");
+  assertEconomyIdentifier(decision.adjustmentId, "adjustmentId");
+  assertEconomyIdentifier(decision.proposalId, "proposalId");
+  assertCanonicalHash6(decision.proposalHash, "proposalHash");
+  assertCanonicalHash6(decision.previewHash, "previewHash");
+  assertEconomyIdentifier(
+    decision.proposedByAccountId,
+    "proposedByAccountId"
+  );
+  assertEconomyIdentifier(
+    decision.decidedByAccountId,
+    "decidedByAccountId"
+  );
+  economyAssert(
+    decision.proposedByAccountId !== decision.decidedByAccountId,
+    "ADJUSTMENT_SELF_APPROVAL",
+    "Operator adjustment approval requires a distinct operator"
+  );
+  economyAssert(
+    decision.adjustmentId === preview.adjustmentId && decision.proposalId === proposal.proposalId && decision.proposalHash === expectedProposalHash && decision.previewHash === expectedPreviewHash,
+    "ADJUSTMENT_PREVIEW_MISMATCH",
+    "Operator adjustment decision does not match its preview"
+  );
+  const proposedAt = parseIsoTimestamp(decision.proposedAt);
+  const decidedAt = parseIsoTimestamp(decision.decidedAt);
+  economyAssert(
+    decision.proposedByAccountId === proposal.proposedByAccountId && proposedAt === parseIsoTimestamp(proposal.proposedAt) && decidedAt >= proposedAt,
+    "INVALID_TIME_WINDOW",
+    "Operator adjustment decision times are inconsistent"
+  );
+  economyAssert(
+    decidedAt <= parseIsoTimestamp(preview.expiresAt),
+    "ADJUSTMENT_EXPIRED",
+    "Operator adjustment preview has expired"
+  );
+}
+function canonicalOperatorAdjustmentDecisionPayload(decision) {
+  assertExactKeys3(decision, DECISION_KEYS, "Operator adjustment decision");
+  return JSON.stringify({
+    schemaVersion: decision.schemaVersion,
+    decisionId: decision.decisionId,
+    adjustmentId: decision.adjustmentId,
+    proposalId: decision.proposalId,
+    proposalHash: decision.proposalHash,
+    previewHash: decision.previewHash,
+    decision: decision.decision,
+    proposedByAccountId: decision.proposedByAccountId,
+    decidedByAccountId: decision.decidedByAccountId,
+    proposedAt: decision.proposedAt,
+    decidedAt: decision.decidedAt
+  });
+}
+function assertOperatorAdjustmentExecution(execution, preview, proposal, decision, expectedPreviewHash, expectedProposalHash, expectedDecisionHash) {
+  assertOperatorAdjustmentDecision(
+    decision,
+    proposal,
+    preview,
+    expectedPreviewHash,
+    expectedProposalHash
+  );
+  assertCanonicalHash6(expectedDecisionHash, "expectedDecisionHash");
+  assertExactKeys3(execution, EXECUTION_KEYS, "Operator adjustment execution");
+  economyAssert(
+    execution.schemaVersion === ECONOMY_CONTRACT_VERSION,
+    "INVALID_CONTRACT",
+    "Unsupported operator adjustment execution"
+  );
+  assertEconomyIdentifier(execution.executionId, "executionId");
+  assertEconomyIdentifier(execution.adjustmentId, "adjustmentId");
+  assertCanonicalHash6(execution.previewHash, "previewHash");
+  assertCanonicalHash6(execution.proposalHash, "proposalHash");
+  assertCanonicalHash6(execution.decisionHash, "decisionHash");
+  assertEconomyIdentifier(execution.sourceLotId, "sourceLotId");
+  assertEconomyIdentifier(execution.transactionId, "transactionId");
+  assertEconomyIdentifier(execution.resultReceiptId, "resultReceiptId");
+  economyAssert(
+    decision.decision === "approve",
+    "ADJUSTMENT_NOT_APPROVED",
+    "Only an approved adjustment may execute"
+  );
+  economyAssert(
+    execution.adjustmentId === preview.adjustmentId && execution.previewHash === expectedPreviewHash && execution.proposalHash === expectedProposalHash && execution.decisionHash === expectedDecisionHash && execution.sourceLotId === preview.sourceLotId,
+    "ADJUSTMENT_PREVIEW_MISMATCH",
+    "Operator adjustment execution does not match its approval plan"
+  );
+  economyAssert(
+    parseIsoTimestamp(execution.executedAt) >= parseIsoTimestamp(decision.decidedAt),
+    "INVALID_TIME_WINDOW",
+    "Operator adjustment execution predates its decision"
+  );
+}
+function canonicalOperatorAdjustmentExecutionPayload(execution) {
+  assertExactKeys3(execution, EXECUTION_KEYS, "Operator adjustment execution");
+  return JSON.stringify({
+    schemaVersion: execution.schemaVersion,
+    executionId: execution.executionId,
+    adjustmentId: execution.adjustmentId,
+    previewHash: execution.previewHash,
+    proposalHash: execution.proposalHash,
+    decisionHash: execution.decisionHash,
+    sourceLotId: execution.sourceLotId,
+    transactionId: execution.transactionId,
+    resultReceiptId: execution.resultReceiptId,
+    executedAt: execution.executedAt
+  });
+}
+
 // src/paid-lots.ts
 var ZERO_ARITHMETIC = Object.freeze({
   retainedDelta: serializeTokenSubunits(0n),
@@ -6842,7 +7194,7 @@ var PORTABLE_KEYS = /* @__PURE__ */ new Set([
   "signature",
   ...PORTABLE_BODY_KEYS
 ]);
-function assertExactKeys3(value, allowedKeys, label) {
+function assertExactKeys4(value, allowedKeys, label) {
   economyAssert(
     value !== null && typeof value === "object" && !Array.isArray(value),
     "INVALID_CONTRACT",
@@ -6854,7 +7206,7 @@ function assertExactKeys3(value, allowedKeys, label) {
     `${label} contains an unsupported field`
   );
 }
-function assertCanonicalHash6(value, label) {
+function assertCanonicalHash7(value, label) {
   economyAssert(
     typeof value === "string" && CANONICAL_HASH.test(value),
     "INVALID_CONTRACT",
@@ -6863,7 +7215,7 @@ function assertCanonicalHash6(value, label) {
 }
 function canonicalHash(payload, hashCanonicalPayload2, label) {
   const value = hashCanonicalPayload2(payload);
-  assertCanonicalHash6(value, label);
+  assertCanonicalHash7(value, label);
   return value;
 }
 function assertUnsignedInteger(value, label) {
@@ -6931,7 +7283,7 @@ function canonicalSignatureMetadata(signature) {
   };
 }
 function assertEconomySealedRecoveryPayload(payload) {
-  assertExactKeys3(
+  assertExactKeys4(
     payload,
     /* @__PURE__ */ new Set([
       "schemaVersion",
@@ -6961,17 +7313,17 @@ function assertEconomySealedRecoveryPayload(payload) {
     22,
     22
   );
-  assertCanonicalHash6(
+  assertCanonicalHash7(
     payload.plaintextContentHash,
     "Recovery plaintext-content hash"
   );
-  assertCanonicalHash6(
+  assertCanonicalHash7(
     payload.encryptionContextHash,
     "Recovery encryption-context hash"
   );
 }
 function assertAcceptanceBody(body) {
-  assertExactKeys3(
+  assertExactKeys4(
     body,
     "acceptanceEnvelopeId" in body ? ACCEPTANCE_KEYS : ACCEPTANCE_BODY_KEYS,
     "Recovery acceptance body"
@@ -6990,9 +7342,9 @@ function assertAcceptanceBody(body) {
     body.idempotencyFingerprint,
     "economy.idempotency-key.v1"
   );
-  assertCanonicalHash6(body.commandEnvelopeHash, "Command-envelope hash");
+  assertCanonicalHash7(body.commandEnvelopeHash, "Command-envelope hash");
   assertEconomyIdentifier(body.acceptedReceiptId, "acceptedReceiptId");
-  assertCanonicalHash6(body.acceptedReceiptHash, "Accepted-receipt hash");
+  assertCanonicalHash7(body.acceptedReceiptHash, "Accepted-receipt hash");
   assertEconomySealedRecoveryPayload(body.sealedPayload);
   const preparedAt = parseIsoTimestamp(body.preparedAt);
   const acceptedAt = parseIsoTimestamp(body.acceptedAt);
@@ -7040,7 +7392,7 @@ function createEconomyRecoveryAcceptanceEnvelope(body, hashCanonicalPayload2) {
   };
 }
 function assertEconomyRecoveryAcceptanceEnvelope(envelope, hashCanonicalPayload2) {
-  assertExactKeys3(envelope, ACCEPTANCE_KEYS, "Recovery acceptance envelope");
+  assertExactKeys4(envelope, ACCEPTANCE_KEYS, "Recovery acceptance envelope");
   assertAcceptanceBody(envelope);
   assertEconomyIdentifier(
     envelope.acceptanceEnvelopeId,
@@ -7081,7 +7433,7 @@ function canonicalEconomyRecoveryAcceptanceEnvelopePayload(envelope, hashCanonic
   });
 }
 function assertCommittedResultBody(body) {
-  assertExactKeys3(
+  assertExactKeys4(
     body,
     "committedResultId" in body ? COMMITTED_RESULT_KEYS : COMMITTED_RESULT_BODY_KEYS,
     "Recovery committed-result body"
@@ -7109,7 +7461,7 @@ function assertCommittedResultBody(body) {
     [body.authorityCommitHash, "Authority-commit hash"],
     [body.authorityHeadHashAfter, "Authority-head hash"]
   ]) {
-    assertCanonicalHash6(value, label);
+    assertCanonicalHash7(value, label);
   }
   economyAssert(
     RESULT_OUTCOMES.has(body.outcome),
@@ -7132,7 +7484,7 @@ function assertCommittedResultBody(body) {
     assertEconomyIdentifier(body.transactionId, "transactionId");
   }
   if (body.transactionCanonicalHash !== void 0) {
-    assertCanonicalHash6(
+    assertCanonicalHash7(
       body.transactionCanonicalHash,
       "Transaction canonical hash"
     );
@@ -7175,7 +7527,7 @@ function createEconomyRecoveryCommittedResult(body, hashCanonicalPayload2) {
   };
 }
 function assertEconomyRecoveryCommittedResult(result, hashCanonicalPayload2) {
-  assertExactKeys3(
+  assertExactKeys4(
     result,
     COMMITTED_RESULT_KEYS,
     "Recovery committed result"
@@ -7234,7 +7586,7 @@ function assertEconomyRecoveryResultLink(acceptance, result, hashCanonicalPayloa
   );
 }
 function assertEconomyEvidenceSignatureMetadata(signature) {
-  assertExactKeys3(
+  assertExactKeys4(
     signature,
     /* @__PURE__ */ new Set([
       "schemaVersion",
@@ -7254,7 +7606,7 @@ function assertEconomyEvidenceSignatureMetadata(signature) {
   parseIsoTimestamp(signature.signedAt);
 }
 function assertEconomyEvidenceSignature(signature) {
-  assertExactKeys3(
+  assertExactKeys4(
     signature,
     /* @__PURE__ */ new Set([
       "schemaVersion",
@@ -7276,7 +7628,7 @@ function assertEconomyEvidenceSignature(signature) {
   assertBase64url(signature.value, "Evidence signature value", 32, 2048);
 }
 function assertRegionalEvidenceBody(body) {
-  assertExactKeys3(
+  assertExactKeys4(
     body,
     "evidenceReceiptId" in body ? REGIONAL_KEYS : REGIONAL_BODY_KEYS,
     "Regional evidence-receipt body"
@@ -7308,7 +7660,7 @@ function assertRegionalEvidenceBody(body) {
     "INVALID_CONTRACT",
     "Unsupported recovery record kind"
   );
-  assertCanonicalHash6(
+  assertCanonicalHash7(
     body.recoveryRecordContentHash,
     "Recovery-record content hash"
   );
@@ -7324,7 +7676,7 @@ function assertRegionalEvidenceBody(body) {
       "INVALID_CONTRACT",
       "Non-genesis regional evidence receipt requires a previous hash"
     );
-    assertCanonicalHash6(
+    assertCanonicalHash7(
       body.previousReceiptHash,
       "Previous evidence-receipt hash"
     );
@@ -7368,7 +7720,7 @@ function createEconomyRegionalEvidenceReceipt(body, signature, hashCanonicalPayl
   };
 }
 function assertEconomyRegionalEvidenceReceipt(receipt, hashCanonicalPayload2) {
-  assertExactKeys3(receipt, REGIONAL_KEYS, "Regional evidence receipt");
+  assertExactKeys4(receipt, REGIONAL_KEYS, "Regional evidence receipt");
   assertRegionalEvidenceBody(receipt);
   assertEconomyIdentifier(receipt.evidenceReceiptId, "evidenceReceiptId");
   assertEconomyEvidenceSignature(receipt.signature);
@@ -7499,7 +7851,7 @@ function assertEconomyRegionalEvidenceChain(receipts, expectedPreviousReceiptHas
       "INVALID_CONTRACT",
       "Partial evidence chain requires its trusted preceding hash"
     );
-    assertCanonicalHash6(
+    assertCanonicalHash7(
       expectedPreviousReceiptHash,
       "Expected preceding evidence-receipt hash"
     );
@@ -7570,7 +7922,7 @@ function assertEconomyRegionalEvidenceEquality(receipts, expectedRegions, hashCa
   );
 }
 function assertEconomyMerkleInclusionProof(proof) {
-  assertExactKeys3(
+  assertExactKeys4(
     proof,
     /* @__PURE__ */ new Set([
       "schemaVersion",
@@ -7591,8 +7943,8 @@ function assertEconomyMerkleInclusionProof(proof) {
     "Unsupported Merkle inclusion proof"
   );
   assertEconomyIdentifier(proof.anchorId, "anchorId");
-  assertCanonicalHash6(proof.anchorManifestHash, "Anchor-manifest hash");
-  assertCanonicalHash6(proof.leafHash, "Merkle leaf hash");
+  assertCanonicalHash7(proof.anchorManifestHash, "Anchor-manifest hash");
+  assertCanonicalHash7(proof.leafHash, "Merkle leaf hash");
   assertUnsignedInteger(proof.leafIndex, "Merkle leaf index");
   assertUnsignedInteger(proof.leafCount, "Merkle leaf count");
   economyAssert(
@@ -7601,7 +7953,7 @@ function assertEconomyMerkleInclusionProof(proof) {
     "Merkle leaf position is outside its bounded tree"
   );
   for (const step of proof.siblings) {
-    assertExactKeys3(
+    assertExactKeys4(
       step,
       /* @__PURE__ */ new Set(["schemaVersion", "side", "hash"]),
       "Merkle proof step"
@@ -7611,7 +7963,7 @@ function assertEconomyMerkleInclusionProof(proof) {
       "INVALID_CONTRACT",
       "Unsupported Merkle proof step"
     );
-    assertCanonicalHash6(step.hash, "Merkle sibling hash");
+    assertCanonicalHash7(step.hash, "Merkle sibling hash");
   }
 }
 function canonicalMerkleProof(proof) {
@@ -7690,7 +8042,7 @@ function assertEconomyMerkleInclusion(proof, anchor, hashCanonicalPayload2) {
   );
 }
 function assertPortableEvidenceReference(reference) {
-  assertExactKeys3(
+  assertExactKeys4(
     reference,
     /* @__PURE__ */ new Set([
       "schemaVersion",
@@ -7710,7 +8062,7 @@ function assertPortableEvidenceReference(reference) {
     reference.evidenceReceiptId,
     "evidenceReceiptId"
   );
-  assertCanonicalHash6(
+  assertCanonicalHash7(
     reference.evidenceReceiptHash,
     "Evidence-receipt hash"
   );
@@ -7727,7 +8079,7 @@ function canonicalPortableEvidenceReference(reference) {
   };
 }
 function assertPortableBody(body) {
-  assertExactKeys3(
+  assertExactKeys4(
     body,
     "portableReceiptId" in body ? PORTABLE_KEYS : PORTABLE_BODY_KEYS,
     "Portable customer-receipt body"
@@ -7766,7 +8118,7 @@ function assertPortableBody(body) {
     [body.committedResultContentHash, "Committed-result content hash"],
     [body.authorityCommitHash, "Authority-commit hash"]
   ]) {
-    assertCanonicalHash6(value, label);
+    assertCanonicalHash7(value, label);
   }
   assertUnsignedInteger(body.authoritySequence, "Authority sequence");
   economyAssert(
@@ -7851,7 +8203,7 @@ function createEconomyPortableCustomerReceipt(body, signature, hashCanonicalPayl
   };
 }
 function assertEconomyPortableCustomerReceipt(receipt, hashCanonicalPayload2) {
-  assertExactKeys3(receipt, PORTABLE_KEYS, "Portable customer receipt");
+  assertExactKeys4(receipt, PORTABLE_KEYS, "Portable customer receipt");
   assertPortableBody(receipt);
   assertEconomyIdentifier(receipt.portableReceiptId, "portableReceiptId");
   assertEconomyEvidenceSignature(receipt.signature);
@@ -8111,6 +8463,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 assertExactKeys5(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) {
+  assertExactKeys5(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) {
+  assertExactKeys5(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) {
+  assertExactKeys5(state, STATE_KEYS, "Wallet initialization state");
+  assertExactKeys5(
+    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"
+  );
+}
 export {
   BASELINE_GBP_CATALOG_VERSION,
   BASELINE_GBP_REFERENCE_RATE,
@@ -8192,9 +8779,16 @@ export {
   assertModuleSpendQuote,
   assertNonNegativeAccounts,
   assertOpenPurchaseIntent,
+  assertOperatorAdjustmentDecision,
+  assertOperatorAdjustmentExecution,
+  assertOperatorAdjustmentPreview,
+  assertOperatorAdjustmentProposal,
   assertPaidLotLifecycle,
   assertPaidLotLifecycleEvent,
   assertPaidLotPurchaseProvenance,
+  assertPersonalWalletInitializationCommand,
+  assertPersonalWalletInitializationOutboxIntent,
+  assertPersonalWalletInitializationState,
   assertPurchaseCapReservation,
   assertPurchaseCapReservationTransition,
   assertPurchaseIntentBinding,
@@ -8252,6 +8846,12 @@ export {
   canonicalEconomyRegionalEvidenceReceiptBodyPayload,
   canonicalEconomyRegionalEvidenceReceiptPayload,
   canonicalEconomyRegionalEvidenceReceiptSigningPayload,
+  canonicalOperatorAdjustmentDecisionPayload,
+  canonicalOperatorAdjustmentExecutionPayload,
+  canonicalOperatorAdjustmentPreviewPayload,
+  canonicalOperatorAdjustmentProposalPayload,
+  canonicalPersonalWalletInitializationCommandPayload,
+  canonicalPersonalWalletInitializationOutboxPayload,
   canonicalTransactionPayload,
   closeModuleAllowance,
   convertRewardPayout,
@@ -8267,6 +8867,8 @@ export {
   createModuleSpendHold,
   createModuleSpendQuote,
   createPaidLotLifecycle,
+  createPersonalWalletInitializationDocumentIds,
+  createPersonalWalletInitializationState,
   createProjectionSnapshot,
   createPurchaseIntentLifecycle,
   createReversalTransaction,