@plasius/economy 0.7.0 → 0.9.0

package/README.md

@@ -437,12 +437,80 @@ principal only and terminates with `WALLET_INITIALIZED` or
 double-entry transaction or Token activity row and does not authorize value or
 provider writes.
 
+`initialize-admin-reporting` is also additive to the audited command union. It
+is restricted to a service principal and the system source so a host can bind
+one create-only reporting bootstrap to its normal authority head, manifest,
+receipt, and idempotency evidence. It does not authorize a balance mutation or
+replace an existing reporting projection.
+
 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
 adapter concerns; `assertWalletActivityPageForPortfolio()` proves that a result
 never expands the authorized portfolio scope.
 
+## Pseudonymous Admin reporting
+
+`AdminEconomyReportingQueryPortV1` defines provider-neutral global summary,
+pseudonymous wallet balance, activity, and trend results for governed finance
+operations. It does not grant access or query a database. A host must
+authenticate the caller, enforce the stored rollout flags
+`economy.admin-history.enabled` and `mcp.admin-economy-history.enabled` as
+applicable, re-check the finance capability, and use a least-privilege
+reporting projection.
+
+The global summary is an identifier-free point-read projection. It contains
+exact available, reserved, held, reward-progress and lifetime totals, wallet
+counts, and the canonical positive authority sequence through which the
+projection is current. Wallet balance pages contain separate audience-bound
+wallet and subject aliases, a closed component/status code, exact non-negative
+amounts, update time, and authority sequence. They are capped at 100 rows and
+support stable available-descending or update-time-descending pagination.
+
+Activity rows are deliberately narrow:
+
+- timestamp, normalized type/status/source, and exact signed TokenSubunits;
+- a closed non-identifying label code that the presentation layer maps to
+  localized text; and
+- distinct opaque row and subject aliases produced by a versioned,
+  audience- and purpose-separated HMAC adapter.
+
+The label-code allowlist is `token-acquisition`, `token-spend`,
+`token-reversal`, `token-hold`, `token-activity-failed`,
+`token-system-adjustment`, and `token-activity-unclassified`. A label must also
+be valid for its activity type.
+
+Failure rows may use exact zero when a failed workflow has no related economic
+transaction or attempted amount. Zero remains invalid for every economically
+meaningful activity type.
+
+The validator accepts only plain enumerable data properties and rejects
+serialization hooks and undeclared properties, including raw account, wallet,
+transaction, order, payment, provider-event, idempotency, and journal-integrity
+identifiers. It also rejects provider-specific source names and free-form
+labels. Result metadata fixes `rawIdentifiersIncluded` to `false`.
+
+Activity pages are capped at 100 rows. Cursor values use a versioned `c1.`
+base64url confidentiality-protected opaque format and cannot contain raw
+identifiers. A resumed request carries both that value and its trusted,
+server-decoded binding to the original window, sort, filters, pseudonym
+audience, and version. Result metadata echoes the normalized filter. The
+deterministic default reporting window is 30 days and the interactive maximum
+is 365 days.
+
+Hourly trends are limited to 31 days and daily trends may cover the maximum
+window. The result ceiling is 3,720 points, covering all five activity types
+through the maximum hourly window. Trend cohorts with fewer than five distinct
+subjects contain only a suppression marker.
+
+Reported trend points carry either a calculated 28-window same-time
+conventional median/MAD indicator or an explicit unavailable result. Only
+non-suppressed baseline cohorts may enter the calculation. Median and MAD
+values use reduced exact rational TokenSubunits with denominators up to two,
+so no floating point or rounding is introduced. Indicators are review alerts
+only and never mutate the ledger. Routine contracts contain no
+identity-resolution operation.
+
 ## Persistence ports
 
 `EconomyPersistencePort` remains exported unchanged for existing consumers.