@plasius/economy 0.5.0 → 0.7.0

package/README.md

@@ -186,6 +186,29 @@ one boundary to durably accept verified evidence before acknowledgement and a
 second boundary to record the externally reconciled completed, failed, or
 no-op result.
 
+## Dual-approved operator adjustments
+
+`OperatorAdjustmentPreviewV1` is the immutable value plan prepared by a
+trusted site adapter. It binds the target account and component to the
+server-resolved wallet, target and offset ledger accounts, deterministic
+source lot, positive TokenSubunit magnitude, bounded reason, hashed ticket
+reference, transfer/refund policy, and expiry. Browser and MCP callers may
+request an account and component, but their wallet or ledger identifiers are
+never authority.
+
+`OperatorAdjustmentProposalV1` records the first operator's pending proposal.
+`OperatorAdjustmentDecisionV1` requires another stable account and binds the
+exact preview and proposal hashes. `OperatorAdjustmentExecutionV1` links an
+approved plan to its source lot, immutable journal transaction and terminal
+result receipt. A correction is a new `reverse-credit` proposal tied to the
+original lot and transaction; the package exposes no set-balance or delete
+operation.
+
+The package validates and canonicalizes these records but deliberately does
+not resolve platform owners, perform MFA step-up, evaluate capabilities or
+flags, hash ticket references, persist proposals, or execute transactions.
+Those controls stay in the consuming authority adapter.
+
 `verifyJournalChainSegment()` accepts an approved canonical-payload hash
 function, recomputes every transaction hash, checks previous-hash links and
 duplicate transaction IDs, and proves the resulting head against an expected
@@ -399,6 +422,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