@voltro/plugin-economy 0.0.0-stage → 0.88.0

package/README.md

@@ -1,3 +1,2720 @@
-# Temporary Holding Version
+# @voltro/plugin-economy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The scoped fixture uses a fresh installed account, accepted SQL period, wallet
+and inventory; provider verification remains an explicit private seam. Scope
+release revokes all four entitlement methods. The policy fixture calls the
+actual default and narrowing path.
+
+Partial SQL wallet and exact-price foundation. Runtime and acceptance validation
+are pending. Immediate virtual/free Shop has an explicit server SQL adapter; its
+optional factory binding is implemented, while IAP/ads and complete monetization
+remain unfinished. No capacity claim follows from configured bounds.
+
+## Install and configure
+
+`economyPlugin()` captures its currencies, service allow-list, work bounds,
+clock, offer price declarations and `priceResolver`. Only this installed instance
+binds to the API app's borrowed `DataStore`. It neither opens nor closes a store.
+The following numbers are example configuration, not deployment pricing.
+
+```ts
+import { defineCurrency, economyPlugin } from '@voltro/plugin-economy'
+
+export const economy = economyPlugin({
+  currencies: [defineCurrency({ id: 'gold', kind: 'soft', cap: '1000' })],
+  realMoney: false,
+  offers: [{
+    id: 'starter',
+    price: { kind: 'virtual', options: [{ currency: 'gold', amount: '11' }] },
+  }],
+})
+// Add this instance to the API app's plugins array.
+```
+
+`realMoney` defaults to `false`. Both `real` and `mixed` declarations are refused
+when disabled; free and virtual prices need no store, IAP or Stripe credentials.
+This switch currently applies to the implemented wallet and price foundation;
+the complete virtual-only monetization stack remains unfinished.
+
+## Exact amounts and prices
+
+`economyAmount()` accepts canonical decimal strings, bigint, or safe integer
+numbers in the signed SQL BIGINT range. Unsafe numbers, fractions, negative zero,
+leading zeroes and overflow are refused. Wire amounts and virtual prices remain
+canonical decimal strings. Caps are positive exact amounts.
+
+`definePrice(price, currencies, realMoney)` detaches and freezes `virtual`
+alternatives, `real` references, `mixed` alternatives or `free`. Virtual options
+name declared currencies and cannot exceed their balance cap. Real references
+use positive safe integer minor units and app-owned store product identifiers;
+they never verify or fulfill a payment. A mixed price uses
+`{ kind: 'mixed', real: { prices, storeProductIds }, virtual: [...] }`.
+
+`priceResolverContext()` captures a price and trusted virtual adjustments:
+integer `discountBps` from zero to 10000 and an exact `minimum` per currency.
+`defaultPriceResolver` is the single exported default: discounts use exact
+integer arithmetic, round upward and respect the floor. `resolvePrice()` admits
+custom output separately: it preserves all payment alternatives, forbids values
+below the trusted floor or above the declaration and keeps real references and
+store products unchanged. Personalized real prices require separately declared
+store variants and verified provider prices; that integration is still open.
+
+The installed `economy.economy.price(subject, offerId, adjustments)` facade uses
+the selected resolver. It accepts only a system Subject or an explicitly allowed
+verified service; a price projection grants no value. The `./pricing` subpath is
+browser-safe. `./testing` supplies the actual default resolver and ledger fixtures.
+
+## Trusted SQL transfers
+
+`economy.economy.service()` returns the installed `EconomyService`; request
+services use the same `EconomyPort` Effect tag. `transfer(subject, input)` accepts
+only system Subjects or verified services explicitly listed in `allowedServices`.
+Users and guests cannot submit balances, credits, debits or transfer values.
+
+Every transfer supplies tenant, independent `requestId`, currency, positive
+exact amount, distinct source/destination accounts, a reason and a reference.
+Accounts are `{ kind: 'system', id }` or
+`{ kind: 'wallet', ownerKind: 'player' | 'guild', ownerId }`. At least one side is
+a wallet. System-to-system and same-account transfers are refused.
+
+The writer seeds durable admission rows, locks wallet subjects in deterministic
+order, then the currency and request receipt. One transaction updates both
+wallets, inserts exactly two balanced ledger postings and commits a metadata-only
+receipt. The receipt has transaction ID, currency, amount and time; no owners or
+references. A committed identical request returns that original receipt forever;
+a changed intention with the same request conflicts. Aborted work may retain a
+pending admission row but never a committed receipt or monetary posting.
+
+Ordinary wallet balances are nonnegative and bounded by the currency cap; the explicit verified hard-currency refund path below may create policy-bound debt. Currency
+configuration is persisted on first admission; later configuration drift refuses
+fresh writes until an explicit migration is designed. Trusted refund debt and Trades are described below; arbitrary GM value writes remain unfinished. Optional Trades is described below. Trusted
+default-wallet Escrow participants are documented below.
+
+## Own reads and ledger rebuild
+
+`economy.mine` and `useWallets()` (`./web`) read only the authenticated user's or
+guest's player wallets. They take no tenant, owner or value input. The query
+observes wallet, subject-admission and currency tables. Missing configured wallets
+project zero; guild authorization and account merging remain open.
+
+`auditWallet()` and `rebuildWallet()` are trusted server operations. Under the
+same subject/currency SQL fences they read the whole bounded wallet ledger,
+validate both postings and the durable receipt state for each transaction, then
+compare or repair the materialized balance. SQL remains the source of truth.
+No timer, process-local mutex, native SQL client or hot cache is introduced.
+
+`maxLedgerRows` is a work bound per wallet/currency, not a capacity promise;
+`maxExportRows` bounds complete export/erase selections. Excess fails with
+`limit_exceeded` rather than silently returning or deleting a prefix. A scheduled
+scheduled consistency execution proof and incremental sinks/sources maintenance remain open; the bounded whole-history report is described below.
+
+## Privacy and inspection
+
+The default SQL wallet declares five table roles: currencies, wallets, ledger, transactions and
+subjects. Export returns the selected player's own wallets and postings. Erase
+removes their wallets and owner links, redacts reference/actor fields across the
+affected posting pairs, and permanently fences recreation and receipt replay.
+Financial debit/credit values remain for conservation and peer rebuilds; they are
+not rewritten by privacy operations. Retained deterministic fence keys are
+pseudonymous, not an assertion of anonymization or a retention-policy decision.
+
+The shared, local and Cloud panels observe `/status`: captured currency IDs,
+caps, price kinds, resolver selection, SQL binding and work bounds. They do not
+list wallet owners, balances, ledger values, payment references or deployments.
+Unknown or invalid configuration observations fail closed; stale data is hidden
+on failure. Payment installation remains false; optional Shop configuration is reported separately.
+
+## Prepared SQL transfer units
+
+The explicit server adapter returned by `dataStoreEconomy` exposes
+`EconomySqlService.prepareTransfer(subject, input)`. It captures trusted transfer
+input, seeds pending admissions and returns an exact-store-bound opaque SQL unit.
+`executeSqlMutations` (`@voltro/database/sql`) can commit it with Inventory units
+and an order writer in one ordinary transaction. A later unit failure rolls back
+accepted wallet values, balanced postings and receipts together. A pending row is
+not payment. Ordinary `transfer` uses this same writer as a single unit.
+
+Recreate units from original SQL identities after restart or uncertain reply.
+Accepted retries preflight terminal SQL before clock. Units never authorize
+player values and must not run inside another transaction. The installed
+EconomyPort remains its ordinary four-method surface; prepared units belong to
+the explicit server adapter. Optional Shop binding is described below; complete
+spend/minor/monetization limits remain open. Source composition tests exist for runtime and all six native variants;
+none has run in this build phase. See the Transactions page in the bilingual public docs.
+
+## Immediate virtual/free Shop SQL source
+
+`defineShopOffer` (`./shop`) captures versioned offers with `Price`, item/currency
+gifts, availability, per-player/per-day/global quantity limits and `oneTime`.
+Every gift is positive and quantities are bounded before multiplication. One-time
+offers have quantity/per-player limit1. Limits use the offer ID across declaration
+versions; a new version does not reset one-time authority. All amounts below are
+illustrative app configuration, not deployment pricing.
+
+`dataStoreShop` (`./server`) binds explicit prepared Economy/Inventory participants
+to the same exact selected app store. Item offers require Inventory; currency-only
+or free offers need no Inventory or payment provider. `realMoney:false` rejects
+real and mixed declarations before binding participants. With real money enabled,
+this immediate writer accepts only free or selected virtual alternatives; real
+payments still require the separately unfinished provider/receipt path.
+
+```ts
+import { dataStoreShop } from '@voltro/plugin-economy/server'
+import { Effect } from 'effect'
+
+// economySql and inventorySql were constructed from this exact selected store.
+const shop = dataStoreShop(store, {
+  currencies: [{ id: 'gold', kind: 'soft' }],
+  realMoney: false,
+  economy: economySql,
+  inventory: inventorySql,
+  offers: [{
+    id: 'starter', titleKey: 'shop.starter', oneTime: true,
+    price: { kind: 'virtual', options: [{ currency: 'gold', amount: '7' }] },
+    items: [{ itemId: 'potion', qty: 2 }],
+  }],
+})
+
+// verifiedSubject comes from the request; no owner/value is supplied by the player.
+const offerView = (await Effect.runPromise(shop.offers(verifiedSubject)))[0]
+if (!offerView) throw new Error('No available offer')
+const receipt = await Effect.runPromise(shop.buy(verifiedSubject, {
+  offerId: offerView.offer.id, offerVersion: offerView.offer.version,
+  offerDigest: offerView.offerDigest, currency: 'gold', requestId: 'request.1',
+}))
+```
+
+The player sends only offer ID/version/server declaration digest, request, optional quantity and virtual currency.
+Tenant/owner come from the verified user/guest Subject. The server captures price,
+gifts and trusted eligibility. A `ShopContextSource.read` is required when an offer
+names a segment, flag or countries; its implementation owns all such checks. It
+can supply trusted virtual price adjustments. It runs outside SQL. Nondefault
+price/context rules require an explicit version; missing prerequisites refuse.
+Availability is evaluated at captured server admission time. Per-day limits use
+UTC civil days; no local-time or rolling-window claim is made.
+
+Five opt-in SQL roles are exported as `shopTables`: tenant purchase/erase/rebuild
+fence, permanent subject fence, immutable offers, orders and limit counters.
+The tenant fence prevents a purchase or erase from racing complete counter repair.
+One shared transaction checks owner/request/definition/limits, runs the actual
+prepared debit and grants, advances counters and commits the captured order and
+actual child receipts. The completion timestamp is captured after preparation;
+all author/source/clock callbacks remain outside replayable SQL callbacks.
+Failures roll back values, counters and fulfilled order together. Pending
+admissions and zero counters may remain; they are not payment or consumption.
+
+Accepted request identity is permanent and intent-bound. Terminal retries return
+the original SQL receipt before clock/source/participants; concurrent accepted
+replay never recharges or grants again. Changed accepted intentions conflict.
+`auditShop` / `rebuildShop` use complete bounded accepted order/definition evidence,
+including retained erased global consumption. They rebuild counters only, never
+repeat transfers/gifts or historical custom callbacks. Whole-history excess
+refuses rather than accepting a prefix. Budgets are not measured capacity.
+
+Export returns complete owned pending/fulfilled order intentions and receipts.
+Erase clears owner links, request/price/receipt bodies and owned day/player
+counters, keeps a permanent owner fence and redacted global consumption.
+Shared definitions and financial conservation stay. Keys remain pseudonymous.
+Shop-only erase does not undo accepted destination gifts: run the Economy and
+Inventory privacy hooks as well. Complete account merge/guild lifecycle remains
+open.
+
+This explicit adapter and five-method ShopPort are implemented. The installed
+economy factory/routes/inspect panel now have opt-in binding, described below;
+absence of configuration still reports Shop absent. The complete virtual-only
+monetization stack is not claimed.
+
+## Install the optional Shop
+
+`economyPlugin({ shop: ... })` now mounts the same default SQL ShopPort or a full
+`shop.service` replacement. Without `shop`, no Shop query/action/tag/table role is
+mounted; `economy.economy.shop()` calls refuse unavailable. Configure both plugin
+instances in one API app and import or publish actual matching item content before
+buying. Example amounts remain illustrative app-owned rules:
+
+```ts
+import { economyPlugin } from '@voltro/plugin-economy'
+import { inventoryPlugin, defineItem } from '@voltro/plugin-inventory'
+import { Schema } from 'effect'
+
+const potion = defineItem({
+  id: 'potion', kind: 'consumable', stackable: true, maxStack: 10,
+  tradable: false, rarity: 'common', tags: [],
+  attributes: Schema.Struct({}), instanceAttributes: Schema.Struct({}),
+  display: { nameKey: 'items.potion' },
+})
+export const inventory = inventoryPlugin({ items: [potion] })
+export const economy = economyPlugin({
+  currencies: [{ id: 'gold', kind: 'soft' }], realMoney: false,
+  shop: {
+    inventory: inventory.inventory,
+    offers: [{ id: 'starter', titleKey: 'shop.starter', oneTime: true,
+      price: { kind: 'virtual', options: [{ currency: 'gold', amount: '7' }] },
+      items: [{ itemId: potion.id, qty: 2 }],
+    }],
+  },
+})
+// Add both instances to the API app's plugins; publish/import the item catalog.
+```
+
+The installed `economy.economy.shop()` service and ShopPort have five methods:
+`offers`, `buy`, `receipt`, `exportSubject`, `eraseSubject`. `shop.offers` is a verified own
+query and `shop.buy` an Action; the latter does not introduce an outer transaction
+around the borrowed writer. `useShopOffers` / `useShopBuy` in `./web` use those
+actual descriptors. Time-only availability needs an explicit refresh. Built-in
+source-specific CDC/region/residency integration and player purchase recovery UI
+remain acceptance/integration work.
+
+The installed Inventory facade exposes `inventory.inventory.prepareGrant` and
+`prepareCraft` for default SQL participation. They capture intentions and refuse
+before binding, after deactivation or when Inventory/full crafting is replaced;
+no SQL fallback is borrowed for a replacement. Exact-store group admission also
+refuses accidental cross-app/physical-store units. Ordinary InventoryPort stays
+eight methods. Prepared API, route and production discovery proof is pending.
+
+A full `shop.service` supplies all five methods, its own durable authority/receipt/
+privacy behavior and an explicit `version`. Required methods are captured without
+accessor evaluation and retain their original receiver, including class methods.
+Default Shop SQL roles/adapter/query sources are omitted, no fallback; actual replacement query sources must be declared. Combining a full service
+with default inventory/context/price/system-account/clock/order/audit options refuses. The app
+owns replacement schemas, placement/CDC, services and lifecycle; the installed
+facade revokes calls after deactivation. Its privacy pair participates with the
+Economy pair; Inventory hooks remain their own plugin's responsibility.
+
+Server `/status`, strict Shared/Cloud/Local contracts and the existing bilingual
+panel now show whether Shop is configured, its backend/rule/context/price slots,
+redacted offer counts/limits and work budgets. Default Shop adds five roles;
+replacement adds none. Rotation, built-in LiveOps and real payment remain false.
+No owner, balance, order, accepted receipt, private attribute or purchase
+outcome is exposed. Failure hides stale Shop content.
+
+
+The default Shop inherits the root `priceResolver`; `shop.priceResolver` explicitly overrides it. An inherited or overridden custom resolver requires an explicit non-default `shop.version`, just as a custom context source does.
+
+## Recover an uncertain virtual purchase
+
+The optional Shop now also mounts `shop.receipt`, a read-only live query.
+`receipt(subject, originalBuyInput)` and `useShopReceipt` return the original
+request ID plus `not-observed`, `pending` or `fulfilled` with the actual
+receipt. Missing/pending evidence is nonterminal: it cannot prove that a
+purchase will never commit and cannot justify a new identity. Reads never seed
+rows, update fences, call the clock, resolve current prices, prepare a
+participant or buy again. Accepted history survives current offer/policy
+changes; a changed accepted intention conflicts. Erased owners are refused.
+
+`./web` exports `createShopPurchaseRecovery` and `browserShopPurchaseJournal`.
+The journal stores only the original offer/version/server declaration digest/request/currency/quantity and an opaque
+app/account/tenant scope, with a version. It stores no price, balance, item state,
+credentials or response body. Supply actual browser storage and Web Locks after
+client initialization; neither is replaced by an in-memory fallback. The journal
+checks persistence before transport and holds the shared lock through settlement.
+
+`selectScope(scope)` invalidates old continuations every time, including a switch
+away and back. Use a stable opaque scope for the authenticated app/account/tenant
+and call it whenever the session selection changes. `begin(input)` durably saves
+the user-selected intention; it never sends a purchase. `retry(originalInput)` explicitly
+submits that saved intention through the installed buy action and settles only a
+matching fulfilled receipt. `observe(result)` may settle matching SQL evidence.
+Failures, malformed/mismatching evidence, unknown/pending observations and scope
+changes keep the original intention. `pending()` restores it after a reload.
+No automatic replay, new-ID retry, optimistic grant or manual nonterminal dismissal.
+
+```ts
+import { browserShopPurchaseJournal, createShopPurchaseRecovery } from '@voltro/plugin-economy/web'
+import type { ShopBuyInput, ShopOrderReceipt } from '@voltro/plugin-economy/shop'
+
+export const purchaseRecovery = (
+  storage: Storage,
+  locks: LockManager,
+  runBuy: (input: ShopBuyInput) => Promise<ShopOrderReceipt>,
+) => createShopPurchaseRecovery(browserShopPurchaseJournal(storage, locks), runBuy)
+// On the client, runBuy is useShopBuy().run without handled-error options.
+// Select the authenticated scope, begin a user-selected intention, then retry
+// only on explicit confirmation. Pass useShopReceipt(originalInput).data to observe.
+```
+
+Fixed-price quote confirmation, permanent withdrawal, account-erase
+browser-journal cleanup, native browser locks, complete player integration and
+full provider fulfillment remain open.
+
+## Version-bound player Shop components
+
+The `./components` entry now contains `ShopGrid`, `OfferCard`, `PurchaseDialog`
+and `PurchaseRecovery`, using the existing shared UI primitives. They emit
+intentions and render observations; they never grant items or change wallet
+state optimistically.
+
+Every offer view includes `offerDigest`, computed by the server from the complete
+immutable declaration and rule version. A buy and its receipt require offer ID,
+`offerVersion` and that digest. Fresh purchases compare them before preparation;
+accepted replays still use immutable historical evidence. A different node with
+a divergent same-version declaration cannot silently substitute another price or
+gift. The browser preserves this identity in its original-intention journal.
+It never computes an authorizing digest or sends a price/balance/item state.
+
+`shopPurchaseTerms(view, intention)` shares the actual pure declaration/price
+admission. It separates the currently displayed discount from the immutable
+maximum charge, with exact decimal-string arithmetic. The dialog confirms that
+maximum explicitly: the personalized discount is not a fixed quote. The server
+may charge up to that ceiling under the saved declaration/rule identity, after
+checking current eligibility/limits. A changed declaration/rule identity conflicts.
+Fixed personalized-price quote confirmation and permanent withdrawal remain open.
+
+The components accept EN/DE copy or a full `ShopUiCopy` override, translated titles,
+currency names and a reward-rendering slot. Offer rows show declared gifts,
+one-time policy and availability countdown using caller-supplied `at`; that clock
+does not poll the backend. No remaining-stock claim follows from configured limits.
+Real checkout is absent; mixed offers expose their virtual alternatives only.
+The dialog uses native protected modal focus through the existing Dialog wrapper;
+busy controls remain focusable and guard activation.
+
+```tsx
+import { ShopGrid, type ShopGridProps } from '@voltro/plugin-economy/components'
+import { useShopOffers } from '@voltro/plugin-economy/web'
+
+export const PlayerOffers = (props: Pick<ShopGridProps, 'at' | 'title' | 'onSelect'>) => {
+  const source = useShopOffers()
+  return <ShopGrid source={source} at={props.at} title={props.title} onSelect={props.onSelect} />
+}
+```
+
+The parent owns the authenticated recovery scope and action admission. Obtain a
+fresh request ID only for a new user-selected intention, save it with `begin`,
+then call `retry` on explicit confirmation. Keep `PurchaseRecovery` above transient
+offer failures/filters and use its saved request unchanged. A failed refresh hides
+stale offer controls without removing saved purchase recovery. Closing the dialog
+does not delete a request. `useShopReceipt(undefined)` skips the query; mount it
+with the original saved input and pass matching data to `observe`. Only actual
+fulfilled evidence settles it. Account-erase browser-journal cleanup remains open.
+
+DOM fixtures substitute the modal methods and lock seam; they do not establish
+native focus trapping, Web Locks, browser layout, dialect parity or a complete
+game flow.
+
+The explicit retry takes the exact original input shown to the user:
+`retry(originalInput)`. It captures it before waiting for the shared lock and
+compares it with the current durable reference before transport. If another tab
+has settled the old request and reserved a new valid purchase, the stale control
+conflicts rather than silently sending that new purchase. Pass the request
+received by `PurchaseRecovery.onRetry`, not a newly minted input.
+
+## Replace the complete wallet port
+
+`EconomyPort` keeps four methods: `transfer`, `mine`, `auditWallet`,
+`rebuildWallet`. `EconomySystemService` adds the required `exportSubject` and
+`eraseSubject` pair for a full installed replacement. Supply that service
+through `economyPlugin({ currencies, service, version, querySources })`. An
+explicit non-default version and a nonempty, unique list of the actual app-owned
+SQL tables for wallet query invalidation are required. The installed
+`economy.mine` route uses those sources; it does not keep the default SQL
+sources. Required methods are captured once without evaluating accessors; class
+receivers are preserved through the same admission used by Shop replacements.
+
+The factory omits all five default wallet tables and never constructs or falls
+back to its default SQL adapter. `now`, `maxLedgerRows` and `maxExportRows` are
+refused with a replacement. The app owns its SQL authority, declared schema,
+conservation, caps, durable request receipts, complete audit/rebuild, lifecycle,
+placement/CDC and privacy behavior. Normal app binding activates the facade;
+deactivation revokes it. A replacement does not turn an unbound facade into a
+working service. The four-method Effect tag and authenticated own-wallet route
+keep the same output contract.
+
+The installed facade still refuses player-authored transfer/audit/rebuild values,
+undeclared transfer currencies and invalid own-subject identity before delegation.
+Only system Subjects or verified services in `allowedServices` can transfer or
+repair. Root price projection remains independent of the wallet backend. The
+replacement must enforce its remaining state and tenant invariants; none is
+proved by the presence of a method. Directly providing a different EconomyPort
+Layer outside this plugin makes the app responsible for equivalent admission.
+
+A default SQL Shop is refused over a fully replaced wallet: it cannot silently
+charge a different default ledger. Supply a complete Shop replacement too, or
+leave Shop absent. Each full Shop requires explicit `shop.querySources.offers`
+and `shop.querySources.receipt`, nonempty unique actual app-owned SQL table lists,
+and a non-default rule version. Default Shop refuses replacement query sources;
+full Shop refuses default clock/participant/context/price/system-account and
+order/audit bounds. The factory retains neither default Shop roles nor query
+sources for that backend. Its dependent five-method ShopPort stays unchanged.
+
+All four inspect layers now distinguish SQL/custom wallet backend and rule
+version, normal app binding and conditional table roles. Default SQL work bounds
+are `null` for a replaced wallet or Shop; panels explicitly label them
+app-owned. No owners, wallet values, purchase outcomes or private replacement
+table names are exposed. Failure hides stale configuration.
+
+## EconomyPort fixture Layer
+
+`./testing` exports `economyPortFixture({ currencies, allowedServices?, now?
+})`: a test-only in-memory four-method port plus its actual `EconomyPort` Layer.
+It reuses `planLedgerTransfer` and `applyWalletPosting` for exact balanced
+rules, stable request receipts, own reads and ledger-derived audits. Provide
+`fixture.layer` with `Effect.provide` when testing a dependent system. This
+fixture grants no SQL, native, durable restart or production proof, and is not a
+deployment backend. The complete system-contract conformance remains open.
+
+The installed default `economy.economy.prepareTransfer` facade participates in same-store atomic game-currency Inventory crafting, refusing inactive/full-replacement SQL borrowing. Ordinary EconomyPort stays four methods.
+
+## SQL sources and sinks aggregate
+
+`readEconomyFlows(store, options)` and `economyFlowsAggregate(options)` live
+only in `./server`, for the default SQL Economy tables. A replaced wallet owns
+its report; these helpers never switch to its sources or a hot cache. Install
+the factory explicitly as an app-owned `*.aggregate.ts` default export. The
+existing aggregate discovery/storage/ refresh/inspection lifecycle owns its
+materialization. No new always-on plugin source, timer or boot change. The API
+Economy template now authors this file. The example tenant and bounds below are
+illustrative configuration budgets.
+
+```ts
+// aggregates/economyFlows.aggregate.ts — server-only file convention
+import { economyFlowsAggregate } from '@voltro/plugin-economy/server'
+
+export default economyFlowsAggregate({
+  tenantId: 'game-demo', name: 'economy.flows', refresh: '1h',
+  maxRows: 10000, maxGroups: 1000,
+})
+```
+
+The reader captures tenant/bounds before laziness and takes a bounded whole
+ledger observation through the borrowed store transaction. It uses the actual
+wallet-audit evidence reader, including durable committed/erased transaction
+receipts, exact conserved pairs, account/identity and matching reason/reference/
+actor checks. Missing pairs/receipts, corrupt values or exceeded work/group bounds
+refuse the entire refresh. Pending receipts carry no value and are not counted.
+Financial rows retained after subject erasure remain in the flow totals; no
+owner, reference, actor, receipt body, wallet balance or tenant ID is output.
+
+One accepted transfer counts once per UTC day/currency/reason: system→wallet is
+a source, wallet→system a sink, wallet→wallet a separate transfer total. Both
+sides are never double-counted. All sums use BigInt and canonical nonnegative
+strings, so a report total may exceed one wallet's signed BIGINT while remaining
+exact. Default bounds are 10,000 ledger rows/1,000 groups; configurable maxima
+100,000/10,000 are admission budgets, not measured capacity. Full history is
+recomputed; incremental retention/archive/large-history reporting is unfinished.
+The projection does not promise a serializable point-in-time snapshot across
+concurrent writes, or refresh a player's wallet value.
+
+Normal aggregate replacement preserves framework stale/error metadata; authorize
+all app query/GM/report reads using the actual aggregate APIs and tenant policy.
+Direct server helpers have no player route.
+
+## Bounded SQL consistency schedule
+
+The default installed facade exposes
+`economy.economy.checkConsistency(systemSubject, input)`, and `./server` exports
+`economyConsistencySchedule` for an explicit app-owned `*.cron.tsx` file. The
+API Economy template now authors that schedule. Existing scheduler admission,
+coordination, overlap, watchdog and run/error tracking own execution; no private
+timer, workflow queue, scheduler replacement or default boot source is added.
+
+```ts
+// schedules/economy.checkConsistency.cron.tsx
+import { economyConsistencySchedule } from '@voltro/plugin-economy/server'
+import { installed } from '../system/installed.server'
+
+export default economyConsistencySchedule({
+  tenantId: 'game-demo', runner: installed.economy,
+  cron: '0 2 * * *', timezone: 'UTC',
+  maxLedgerRows: 10000, maxWallets: 1000,
+})
+```
+
+Whole bounded SQL ledger evidence is admitted by the same actual conserved-pair
+reader used by wallet audit/report. The union of live financial ownership and
+actual wallet materializations includes a wallet even if its materialization was
+deleted. Canonical materialized identities and known currencies must match.
+Each selected wallet uses the existing actual audit under its ordinary durable
+fences. Audit may seed/fence metadata; this job never invokes repair or changes
+balances. It returns only checked/mismatch/ledger-row counts and a matches flag.
+Erased ownership is excluded; retained anonymous financial evidence is still
+validated. Foreign tenants are not selected. System Subjects only; player calls
+refuse before SQL. Lazy input capture, inactive/replaced root refusal and no
+fallback preserve the installed owner. A replacement owns its consistency job.
+
+A mismatch fails the ordinary cron body with a redacted conflict code. Corrupt,
+erased-during-run, unknown-currency, missing or oversized evidence makes the job
+fail rather than report a prefix as green. Default whole bounds are 10,000 ledger
+rows and 1,000 wallet/currency units; configurable maxima 100,000/10,000 remain
+budgets. A transfer after enumeration belongs to the next run; this is not a
+serializable fleet-wide cut. Operator-controlled rebuild remains the existing
+separate trusted operation. No automatic compensation or missed-workflow crash
+recovery is claimed; recurring scheduler behavior still needs actual execution.
+
+No run number or support claim follows.
+
+## Canonical system-contract fixture exports
+
+`./testing` exports `priceResolverSystemFixture`, `economyFakeLayer` and
+`economyPortSystemFixture` beside the existing declaration and configurable
+four-method fixture. The slot probe uses the actual exported Price default and
+an admitted composed override with a distinct result. The canonical fake Layer
+creates one fresh memory fixture per Effect scope; its release closes that
+fixture and escaped service calls refuse. Explicit `economyPortFixture(options)`
+also exposes idempotent `close`; its ordinary Layer.succeed remains owned by the
+caller's fixture lifetime. It calls shared pure ledger planning/wallet
+arithmetic, no SQL imitation or production backend.
+
+These exports fit the existing system suite's fixture shape; they do not
+establish per-table privacy/event/inspect/mixin/upgrades or a complete
+`systemContractConformance` registration/pass. SQL durability/native evidence
+comes from the real adapter scenarios, not this memory Layer.
+
+## Starter packs and explicit offer experiments
+
+The browser-safe `./offer-policies` entry provides `defineStarterPack`, `starterPackAvailable`, `defineOfferExperiment`, `defaultExperimentBucket`, `resolveOfferExperiment` and `offerPolicyContextSource`. These functions compose the existing Shop declaration, trusted context and SQL writer. No new plugin, store, hot cache, parallel grant path or always-on boot work.
+
+A Starter pack captures one existing offer with quantity1/per-player1/oneTime, an explicit positive first-session duration and optional exact currency multiplier. The multiplier becomes immutable offer content and is validated against the actual currency cap. Existing unversioned Shop counters accept the pack once per owner, including alternate request IDs; an accepted original request replays before clock/context even after the offer expires. The availability window is half-open from the trusted first session. This is per-offer first-purchase bonus, not an atomic account-wide never-paid rule. Account-merge identity continuity is still open.
+
+Experiments capture explicit ID/version, half-open UTC dates, sorted weighted variants, complete distinct immutable Shop offers and metric names. Default bucketing is deterministic from tenant/experiment/version/trusted canonical key; it is no security RNG or durable assignment. The identity source must preserve this key across guest upgrade/merge. Real/mixed variants require distinct store products per configured channel. `realMoney:false` refuses real/mixed variants at declaration; virtual/free variants require no third-party credentials. Each variant keeps its own product/offer/digest, never a client-forged storefront price or a replacement real-price reference. Exposure events, persisted assignment/metrics/GM experiment reports and provider settlement remain open.
+
+`offerPolicyContextSource` binds the real class/function receiver, captures configuration and reads trusted facts outside SQL callbacks. Its source receives only verified tenant/owner scalars, admitted offer and observation time; auth scopes/provider metadata are not forwarded. It combines existing eligibility and floor-validated virtual adjustments with Starter windows and the selected experiment offer. Altered declared content refuses. Add the actual resulting offers and this context source to the ordinary Shop configuration with an explicit nondefault rule version. The application still owns authoritative first-session/key/segment/flag/country facts. Snapshot eligibility is no serializable mutable-profile/spend-limit contract. Missing source data refuses; no dummy facts or fallback.
+
+Existing inspect surfaces show the configured custom context; dedicated experiment/Starter controls remain open.
+
+## Exact container disclosure, pity and server sampling
+
+The browser-safe `./containers` entry captures `defineContainer` content with explicit currency registry/global money switch, immutable ID/version/shared-counter group, ordinary Price, bounded positive weighted drops and optional pity. Gifts use actual currency caps and exact signed-BIGINT amounts. `pity.guaranteed` names an existing rarity; `after` is the guaranteed attempt count, and optional `softFrom`/`softRampBps` use exact integer basis points. No float accumulation. Example counts and probabilities are app-owned test configuration.
+
+`containerProbabilityContext` captures the real currency registry and declaration before evaluation. `defaultContainerProbability` preserves relative weight within guaranteed/non-guaranteed groups while increasing the guaranteed probability by an explicit basis-point increment from the soft threshold. `resolveContainerDistribution` admits detached nonnegative integer weights, all known unique drop IDs and a positive bounded total; custom slots cannot violate hard pity. `discloseContainer` exposes the same exact numerator/denominator values used by `resolveContainerRoll`. Hard pity permits only the guaranteed rarity on attempt `after`; a hit resets misses to zero. Without pity there is no miss counter. Public rational disclosure is exact and may exceed wallet BIGINT; it is not a floating percentage.
+
+`defaultContainerRoll` is the single weighted selection default. `ContainerRandomPort` is explicit server authority; the `./server` exports `cryptoContainerRandom`, `cryptoContainerRandomLayer` and `sampleContainer`. The native source uses cryptographic rejection sampling, masks excess bits and refuses after a budget of128 rejected draws. No modulo bias, Math.random, player seed/state or automatic backend switch. Sample preparation captures caller data, evaluates the probability slot once and reuses that exact distribution after deferred draw. Custom roll must choose an admitted positive-weight outcome; custom random ports must supply uniform bounded draws.
+
+This is **sampling, not opening/fulfillment**. No player container route, debit, grant, persistent group counter, SQL journal/rebuild, privacy role, age/country gate or atomic payment/pity acceptance is installed. Ordinary authoritative acceptance must commit the chosen result with actual prepared debit/grants and owned durable history; retry must never draw again. Dedicated four-layer container controls and the full legal/virtual-only contract remain open. Test-only random Layer and actual default/override/port probes are in `./testing`.
+
+`offerExperimentFixture` and `experimentBucketSystemFixture` expose the actual deterministic default and a distinct admitted override through the server/testing entry.
+
+## Code redemption adapter
+
+`./codes` declares `defineCode`, CodePort and code intentions. A declaration contains immutable ID/version/campaign, actual capped currency/item gifts, half-open dates and explicit positive global/per-player limits. It contains no code token. Players supply only case-sensitive code and original request ID; amounts, recipients, gifts and state remain server-owned. Runtime code values are provided privately, never examples, credentials or placeholder tokens.
+
+The server `dataStoreCodes` borrows one ordinary DataStore and the actual Economy/Inventory prepared participants. Four exported roles are `_voltro_eco_code_tenants`, `_voltro_eco_codes`, `_voltro_eco_code_subjects`, `_voltro_eco_code_claims`. SQL stores only scoped SHA-256 code digests and captured declarations, never plaintext codes. Issuing is trusted system/explicit service only. Definition/code identity is immutable; a changed declaration under the same code refuses.
+
+Tenant/owner fences serialize acceptance and erasure. Bounded complete accepted claim history is the global/per-owner counter truth; no independent mutable counter cache. Actual wallet postings, item movements and code receipt commit through the same exact-store prepared group. Rejected grants roll back wallet value and leave a pending original identity, never accepted gifts. Captured completion time and code windows are checked before acceptance preparation. Terminal original retry returns before current clock/declaration/provider preparation. Accepted intent retains its original currency registry for replay/privacy after declaration removal. Own receipt reads distinguish pending/not-observed from fulfilled and never authorize a fresh nonce.
+
+Export/erase methods are complete for these roles. Subject erasure clears owner/intent/digest/receipt bodies, preserves a permanent subject fence and accepted flag/code-key/owner-key evidence so global usage cannot reset. Shared definitions remain. Retained deterministic keys/digests are pseudonymous, not anonymous. Owner export after erasure is empty. Cross-system wallet/item privacy still runs through those owning plugins; code-only erasure cannot revoke gifts. Financial/movement child-reference conformance and archival retention require further evidence.
+
+Optional `economyPlugin({ currencies, codes: { inventory } })` now installs CodePort, four default SQL roles, `economy.redeem` action and owned `economy.codes.receipt` live query. Omit inventory for currency-only gifts; item declarations without a participant refuse. No Code config means no Code tables, routes or Layer. `economy.economy.codes()` exposes the captured installed service. Trusted `create` accepts a privately supplied runtime code; no player or inspect issuance action is mounted. `useRedeemCode`/`useCodeReceipt` in `./web` use the actual browser-safe descriptors. The client sends only code/request identity; a missing or pending observation never authorizes a new request. Durable client recovery and account-erase client cleanup remain open; do not store code values in a browser journal or logs.
+
+`defaultCodeEligibility` is the single exported default. `resolveCodeEligibility` captures the declaration, timestamp and accepted SQL counts; custom pure `codes.eligibility` may narrow admission, never raise hard dates/limits. Custom rules require explicit non-default `codes.version`. Callbacks run outside replayable SQL callbacks; acceptance rechecks captured count basis for custom rules and hard limits under fences. Persisted definitions bind rule versions; accepted receipts preserve historical rule identity and currencies without comparing current configuration on terminal retry. No cross-process/native race claim is inferred from these source checks.
+
+A full `codes.service` replacement must implement all five CodeService methods, use non-default `codes.version` and supply nonempty actual `codes.querySources.receipt` tables. Required methods are captured with class receivers and without evaluating accessors. Replacement owns schema/CDC/authority/receipts/complete privacy; no default roles, bounds or fallback. Default participant/clock/policy/bound options are refused with a replacement. Default SQL Codes over a fully replaced wallet refuses. Installed creation retains trusted Subject checks, player routes derive own verified Subject, and deactivate revokes delegation. Normal export/erase invokes root Economy plus each configured optional system; destination Inventory privacy remains owned by Inventory.
+
+Server `/status`, strict Shared/Cloud/Local contracts and the bilingual panel now show installed backend, rule/eligibility binding, item participant and work bound, never token, subject or accepted outcomes. Default Codes adds four roles; full replacement adds none and reports null SQL bounds. Referral and durable client recovery remain explicitly absent. Existing read-only providers carry the same observation; no new write capability is implied. `./testing` provides `codeEligibilityFixture`, the actual default/override probe, fresh scoped `codesFakeLayer` and actual installed CodePort probe. Production discovery/auth/live delivery, generic conformance, child-reference/archival proofs, GM issuance, referral workflow and complete monetization remain open.
+
+
+## Durable SQL Container opening
+
+`./server` now exports `dataStoreContainers`, captured `resolveContainersStoreOptions`, `containerDefinitionDigest` and four separate roles: container tenants, immutable definitions, subject fences and opening history. `ContainersPort`/five-method `ContainersService` lives in browser-safe `./containers`. The adapter borrows actual prepared Economy/Inventory writers; no alternate debit/grant path, hot data store or tick work.
+
+Configured content uses real Price, optional allowed-country content and shared Pity groups with identical policies. `realMoney:false` refuses real/mixed declarations; free/virtual opens need no providers. Real-payment fulfillment remains absent. Required `accessSource` supplies trusted age/country/eligibility/virtual adjustments for the verified owner. No unknown-age/adult fallback. `defaultContainerEligibility` and `resolveContainerEligibility` preserve no-minors/country/eligibility guards; custom pure eligibility may narrow only. App source and rules require explicit non-default version. Actual age-verification/provider integration and approved legal exemptions remain open.
+
+Own list reports exact Pity-adjusted probabilities, immutable declaration/rule identity and a server `disclosureDigest` tied to owner/history/distribution. An opening intention contains those observed identities, request ID and optional virtual currency, never a draw, seed, amount, probability or player state. Fresh opening conflicts if SQL history or same-version probability output no longer matches the observed disclosure. Current displayed discount is not a pinned quote; the captured declaration bounds payment. Source/RNG/custom policy callbacks occur outside replayable SQL callbacks.
+
+One unresolved original request per owner serializes openings across groups. SQL reserves declaration, original currency registry, historical sequence/Pity and exact disclosed distribution before sampling. The admitted draw/drop/price is durably selected before actual participants prepare. Repeated pending requests reuse that selection; concurrent initial samplers may draw before one SQL selection wins, but only the admitted selection can fulfill. No guarantee that RNG is invoked exactly once across a pre-selection crash. A new nonce cannot bypass a pending original. Failed grants roll back wallet/items/accepted sequence and retain the original selection; fixing actual stock allows the same request to proceed. Permanent cancellation/GM repair of unresolved originals remains open; do not substitute a new request.
+
+Prelude rechecks owner/pending/selected content/history/Pity under fences. Actual debit, chosen currency/item grants, accepted opening receipt and owner-slot release share one exact-store SQL group. Sequence-ordered accepted history is Pity truth/rebuild source; there is no mutable Pity counter/cache to reconstruct. Shared groups require matching historical policy. Hard Pity resets on a hit; fresh disclosure changes after acceptance.
+
+Terminal original retry/own read admits historical content, rules, distribution and child receipts before current declarations/clock/facts/RNG/preparation. Export/erase owns these four roles after declarations change; erase removes subject/intention/selection/receipt bodies and leaves permanent owner fences/pseudonymous IDs. Shared definitions remain. Wallet/item erasure still runs through those owners. Factory/replacement/lifecycle are now available below.
+
+Facts/RNG are explicit fixture seams, not age-verification or entropy proof. Native DDL/cleanup includes all four roles. `containerEligibilitySystemFixture` uses the actual default/override; canonical installed ContainersPort Layer is now available below; full registration remains open.
+
+
+## Installed optional Containers
+
+`economyPlugin({ currencies, containers: { containers, version, accessSource, inventory } })` now installs the captured SQL ContainersPort, four optional roles, own `economy.containers`/`economy.containers.receipt` queries and `economy.openContainer` action. Omit inventory only for currency-only drops. Required trusted access source supplies actual age/country facts with no adult default; it requires explicit non-default rule version. The root `realMoney` switch controls every declaration. Root price resolver is inherited unless explicitly overridden. Only configured systems add roles/routes/Layers; `economy.economy.containers()` refuses while absent or inactive.
+
+Default receipt/list sources are actual Container SQL tables. Optional `containers.querySources` adds real app-owned invalidation tables for external access/price facts; clocks and non-SQL facts still require explicit freshness integration. A complete five-method `containers.service` replacement requires non-default version and actual nonempty list/receipt source tables. It owns schema/CDC/legal authority/receipts/privacy with no default SQL roles/bounds/fallback. Default participant/clock/strategies/random/source/bound options are refused with a replacement. Default SQL Containers over a completely replaced wallet refuses. Required methods retain class receivers without reading getters. Installed gateway preserves own verified Subject checks; replacement remains responsible for its legal/financial contract.
+
+Normal bind/deactivate/export/erase invokes each configured optional system. Economy and Container hooks own their roles, while Inventory still owns destination erasure. Backend/rule identity, probability/roll/eligibility/price/RNG binding, redacted content counts/groups/Pity thresholds and work bounds are shown by server status, strict Shared/Cloud/Local decoder and bilingual configuration panel. No player Pity, draws, owner data, selections, outcomes or wallet values. Custom service reports app-owned RNG/null SQL bounds; real-payment/GM/client-recovery installation remains false. The existing read-only provider paths carry the new observation; refresh errors hide stale content and retain the reload control/focus. No GM write capability is implied.
+
+`useContainers`, `useOpenContainer` and `useContainerReceipt` use the actual browser-safe descriptors. They neither persist a client journal nor replay automatically. Send only the observed declaration/disclosure identities and original request/currency choice. Missing/pending stays nonterminal. Uncertain selected originals cannot be discarded for a new nonce. Full player components, native/browser durable recovery, original cancellation/GM repair and real-payment fulfillment remain open.
+
+`./testing` now exports actual installed scoped `containersPortFixture`, `containersFakeLayer`, `containersPortSystemFixture` and the actual default eligibility probe. Each scope uses a fresh memory store and revokes escaped service access through normal plugin deactivation. Explicit test facts/RNG are seams, not production age or entropy proofs. Templates await actual trusted age-source integration; no fake adult default is installed there.
+
+
+## Subscription calendars and daily-grant rules
+
+The browser-safe `./subscriptions` entry provides `defineSubscription`, `SubscriptionsPort`, replacement-method capture and intention admission. Content includes the existing Price, a day/week/month period, captured on-purchase/daily item and currency gifts, grace days and required duration/renewal copy keys plus an app-local cancellation path. The global `realMoney:false` switch refuses real/mixed declarations; virtual/free content requires no provider credentials. Cooling-off defaults to fourteen days. A shorter declaration requires an explicit application reason; this config is not a legal-compliance result. Perks and country/age authority remain unfinished.
+
+`defaultSubscriptionPeriod` uses UTC, exact day/week durations and calendar months anchored to the original purchase time. A Jan31 origin clamps to Feb28/29 and returns to Mar31; it never derives the next month from the previously clamped date. `resolveSubscriptionPeriod` captures content and time before the slot. A custom resolver requires an explicit non-default rule identity and may narrow the canonical half-open window, never extend or overlap it. It may leave a gap. Work counts/time ranges are admission budgets, not capacity claims.
+
+`defaultSubscriptionDailyGrant` decides eligibility in active or explicitly admitted grace windows. `resolveSubscriptionDailyGrant` uses an absolute UTC day, rejects duplicate claimed days and requires a named custom rule. A custom policy can deny an eligible grant but cannot permit a duplicate, early, expired or out-of-grace claim. The caller must supply complete authoritative SQL receipt history; this pure decision does not persist or prove idempotency. Local client timezone and client-supplied state are never grant authority.
+
+`SubscriptionsPort` declares list/active/start/renew/claimDaily/cancel/export/erase. A complete replacement retains class receivers and refuses method getters. Player start intents carry observed content/version/digest, original request and currency choice. Daily/cancel intents carry only entitlement/request IDs. Renew is a trusted server intention; implementations must deny players and independently fence the entitlement/period. No price, dates, consent, claimed days or provider state is accepted as player value authority. Optional factory installation is described below.
+
+No new tables, settlement, automatic debit, failure-grace transition, Inbox delivery, privacy implementation, SQL rebuild, panel installation, provider integration or canonical port fake Layer is implied. No support claim follows from these declarations.
+
+
+## Ordinary virtual Subscription SQL adapter
+
+`./server` now exports `dataStoreSubscriptions`, option admission, declaration digest and four Subscription table roles. Optional factory installation of this borrowed-DataStore adapter is described below. Explicit trusted access/renewal-consent source and non-default rules identity are mandatory; there is no consent fallback. The source receives verified owner/tenant scalars, captured content, start/renew kind and observation time. It runs outside replayable SQL callbacks. Real/provider settlement is absent; the adapter can select free or virtual alternatives through the actual Price guard.
+
+Start uses observed declaration/version/digest, original nonce and currency choice. Actual prepared wallet debit/on-purchase currency gifts/item grants, accepted event and entitlement commit in one exact-store group. A genuine item/funds failure accepts no entitlement or value; participant pending admissions may remain. Complete sequence-ordered accepted events reconstruct current entitlements and UTC claimed days; there is no mutable entitlement/day cache. One existing unexpired/grace entitlement per content ID refuses another start. A new lifetime after expiry has its own origin and entitlement identity. Bounded complete history is required; archive/retention extension is open.
+
+Daily claims carry only own entitlement/request IDs. Original accepted requests return historical receipts before clock/current declaration/source/preparation; another nonce cannot grant the same entitlement/UTC day. SQL prelude serializes owner history and checks the captured sequence basis. Parallel changed bases conflict and must reread; the framework does not silently retry callbacks or invent a new nonce. Preparation completion rechecks expiry and UTC-day crossings before acceptance. Child receipts use actual existing wallet/item writers, not duplicated transfer/grant code.
+
+Renew is system-only and takes explicit tenant/owner/entitlement/request IDs. It requires original renewal consent plus current trusted consent/eligibility, due expiry and the next anchored window. It accepts at most one next period independently of nonce. It neither charges future periods early nor bulk-charges old missed months. Scheduling, durable consent acquisition/revocation events, payment-failure transitions and overdue repair remain open. Configured grace permits daily grants after expiry; cancellation suppresses that grace. This is not a verified provider-payment-failure policy. Cancel removes renewal authority without shortening an already paid active period or writing a refund; withdrawal/refund settlement is open.
+
+Owning export/erase covers all four roles after current content/currencies change. Erase clears owner/event intent/receipt bodies and retains permanent subject fences plus pseudonymous event IDs/sequence/time; shared immutable declarations remain. Wallet and Inventory retain their separate privacy responsibilities. No Tick, hot cache, native connection or always-on boot work is introduced by this opt-in server factory.
+
+Native DDL/cleanup includes each new role. Read/reconstruction, conservation, genuine grant rollback, UTC nonces, original replay, trusted renewal, class consent receiver, cancellation and owning privacy are source scenarios, not observed runtime results.
+
+
+## Installed optional Subscriptions
+
+`economyPlugin({ currencies, subscriptions: { subscriptions, version, accessSource, inventory } })` now installs the default SQL `SubscriptionsPort`, its four roles, normal lifecycle/privacy and own list/active/start/daily/cancel RPCs. Omit Inventory only when both grant declarations contain no items. Root `realMoney` and Price resolver are inherited; no source or consent is manufactured. No configuration means no Subscription roles/routes/Layer; absent or inactive facade access refuses. Trusted `renew` stays server-only, with no player renewal RPC or built-in scheduler. Earlier statements that this factory is absent are superseded.
+
+A complete nine-method `subscriptions.service` replacement requires explicit non-default version, content and actual nonempty list/active query sources. It retains class receivers without invoking getters, owns authoritative schema/CDC/consent/receipts/lifecycle/privacy and has no default SQL roles, participant options, work bounds or fallback. Default SQL Subscriptions over a completely replaced wallet refuses. Default query sources can add actual app source tables; external fact and clock freshness remain explicit application integration. No native connection or Rooms/CLI boot hook is added.
+
+Server status, strict Shared/Cloud/Local observations and EN/DE panel show backend/rule identity, period/daily/price slots, declaration IDs/periods/grant type counts/grace and SQL work bounds or app ownership. They expose no consent documents, owner IDs, active entitlements, receipts or values. Real-payment/automatic-renewal/GM/client-recovery capabilities remain false. Existing read-only selected-mount/replica providers carry the full observation; failure hides stale configuration and preserves the reload control/focus. No GM write permission follows from this panel.
+
+`useSubscriptions`, `useActiveSubscriptions`, `useStartSubscription`, `useClaimSubscriptionDaily` and `useCancelSubscription` use the actual browser descriptors. They neither persist original intents nor automatically replay or schedule renewal. List displays declaration ceilings, not a pinned personalized quote. Applications must render required duration/renewal/cancellation disclosure and implement consent acquisition before supplying authority. Built-in player components, read-only original-intent recovery query/journal, Inbox/perks, consent/revocation events, failure/overdue repair and provider/refund/withdrawal remain open. Templates do not install fake consent.
+
+`./testing` exports actual installed fresh memory-store `subscriptionsPortFixture`, scoped `subscriptionsFakeLayer` and the actual port/default slot probes. Normal plugin deactivation revokes escaped services. Consent facts are explicit test seams, not production/legal evidence.
+
+
+## Read-only Subscription originals
+
+`SubscriptionsPort` now has nine required methods, adding `receipt`; earlier eight-method references are superseded. `economy.subscriptions.receipt` and `useSubscriptionReceipt` observe a captured original start/daily/renew/cancel intention for the verified owner only. A start read carries its original declaration/version/digest/currency. Other reads carry entitlement/request IDs. Trusted renewal observation derives owner/tenant from the player's verified Subject; it does not grant renewal authority or mount a renewal action.
+
+Default SQL observation performs reads only. It seeds no rows, evaluates no clock/current declaration/consent/strategy/prepared writer and neither reissues nor cancels an uncertain operation. Accepted originals use retained immutable definition/receipt evidence; changed accepted intents conflict. Missing evidence is `not-observed`, a nonterminal observation that cannot authorize a replacement nonce. Erased owners refuse. There is no pending event value row before the atomic group commits, so absence may coexist with an in-flight group. Full replacements must implement this ninth method and declare actual nonempty `querySources.receipt` tables alongside list/active.
+
+Tests inspect all owned rows before/after the actual read and put throwing clock/authority/preparation controls behind it. Installed route/replacement/schema sources are aligned.
+
+
+## Loyalty declarations and rules
+
+The browser-safe `./loyalty` entry provides `defineLoyalty`, exact purchase-point projection, tier/perks strategies and the eight-method `LoyaltyPort`. Content captures ID/version/title, named real or virtual purchase sources with exact positive integer numerator/denominator, unique ordered tiers beginning at zero and XP multiplier/discount/badge/Inbox-gift perks. Gift admission reuses the actual Shop/currency caps. Virtual sources use the app currency registry; real sources require the global money switch and an ISO-style currency code. `realMoney:false` refuses real sources before binding and needs no provider credentials for virtual points. All limits are configured admission budgets, not measured capacity.
+
+`loyaltyPointsForPurchase` projects trusted accepted amounts with exact BigInt arithmetic and floors once per purchase. It neither verifies a provider receipt nor writes points. `defaultLoyaltyTier` selects the highest earned threshold; named overrides may choose only an earned declared tier. `defaultLoyaltyPerks` returns its declared perks; the named perks slot may narrow only to a unique subset of those exact perks. Hidden, amplified or unearned perks refuse. These pure rules apply no Config override, XP/Price hook, badge or Inbox gift.
+
+`projectLoyaltyPoints` is the one whole accepted-history arithmetic/graph projection used by the SQL writer and rebuild. It captures original purchase amount/weights and cumulative linked refunds; sequence gaps, duplicate purchases/refunds, time/refund regression, over-refund and signed-BIGINT overflow refuse. Partial reversals use the difference between original remaining points before and after the cumulative refund, rather than rounding each refund independently. A33-unit refund against1999 units at3/100 reduces59 points to58; a full refund removes the remaining58. Original-season reversals cannot consume current-season points. Arithmetic alone establishes neither receipt authenticity nor owner/complete-query custody; the SQL owner and trusted sources establish those separately.
+
+## Durable and optional Loyalty
+
+`./server` exports `dataStoreLoyalty`, `resolveLoyaltyStoreOptions` and five borrowed SQL roles: tenant fences, immutable definitions, subject fences/tail count, accepted entries and immutable seasons. It opens no native connection, uses no hot backend, reads/writes nothing in a tick and adds no CLI/Rooms boot hook. Complete ordered accepted entries are point truth and rebuild source; there is no materialized points cache. A durable per-subject end count rejects a missing history tail, in addition to sequence/owner/definition/season/arithmetic checks. Bounded complete history is required; archival expansion remains open.
+
+Required `receiptSource.purchase/refund` methods must read actual accepted authority evidence and verify tenant, owner and canonical authority/purchase/refund identity. The source receives no player amount, weight, points or season. Purchase evidence carries the accepted amount/currency/kind/time and must refuse already-refunded or revoked purchases. Refund evidence carries the verified cumulative refunded amount. Explicit non-default rule version is mandatory. Sources/clock and strategy callbacks run outside replayable SQL callbacks. SQL serializes admission through tenant then subject fences and checks the unchanged complete tail before accepting an entry.
+
+Purchase custody hashes tenant/logical loyalty ID/canonical authority/purchase independently of owner, content version and source aliases. Aliases and a new request nonce cannot credit the same receipt again. Refund custody likewise prevents replay/rebinding. Every reversal follows the original archived ratio, definition and season, even when current declarations have changed. Old-season refunds update the old season only. Seasonal programs require an explicit trusted `seasonSource`; accepted seasons retain immutable half-open bounds and reject changed identity or overlap. The current season view starts at zero without deleting old evidence or inventing a calendar. A logical program cannot silently change its decay mode after SQL admission.
+
+`shopLoyaltyReceiptSource(store, { shop, refunds? })` reads an actual fulfilled default SQL Shop order and invokes its owning read-only original receipt service. It derives accepted virtual price and time from that receipt, never the current offer or a submitted price. Free/unsettled/foreign/mismatched orders refuse. This helper is for the default SQL Shop schema; a fully replaced Shop supplies its own receipt authority. The helper supplies no refund writer: omission of a verified refund source explicitly refuses reversals. It creates no automatic purchase consumer and does not make Shop purchase/refund and points one cross-system transaction. Catch-up, complete provider verification/refund settlement and cross-system consistency remain open.
+
+`economyPlugin({ currencies, loyalty: { loyalty, version, receiptSource, seasonSource? } })` installs the default port, five roles, own `economy.loyalty`, `economy.loyalty.mine` and `economy.loyalty.receipt` queries, actual Tag and normal lifecycle/privacy hooks. `economy.economy.loyalty()` refuses while absent or inactive. There is no player credit/reverse/rebuild RPC. Those methods require a system Subject or a configured verified service; their captured intentions contain identities only. Player queries derive tenant/owner exclusively from Subject. `receipt` and trusted `rebuild` read accepted history without seeding rows, clock, current sources, slots or writes; missing is a nonterminal observation, never a new credit authority. Rebuild also works after current definitions are removed.
+
+A complete `loyalty.service` replacement requires all eight receiver-bound methods, explicit non-default version/content and actual nonempty `querySources.list/mine/receipt` tables. Accessors refuse without invocation. It owns schema/CDC/receipts/season authority/privacy and has no default roles, bounds, source/strategy/clock options or fallback. Default sources may explicitly add actual app invalidation tables. Loyalty points are independent borrowed SQL truth over an explicitly supplied receipt source, so a replaced wallet does not acquire default wallet participants. Root real-money admission still applies. Time-only seasonal transitions require explicit refresh.
+
+Export/erase owns all five roles after current content/currencies are removed. Erase clears owner/intent/evidence/point bodies and retains permanent subject fences, pseudonymous event identities, sequence/time and hashed purchase/refund custody. Shared immutable definitions and seasons survive erasure. Wallet, Shop and Inventory keep their own erase hooks; this port does not erase their values or infer merge continuity. A receipt cannot become fresh authority for another owner after erasure.
+
+All four inspect layers and EN/DE panel show optional backend/version, tier/perks slots, source/season binding, redacted declaration type counts, conditional roles and SQL budgets or app ownership. They expose no owner, purchase reference, points, tier outcomes or refund evidence. Provider receipt verification, automatic consumption, perk effects and GM actions remain false. Shared/Local/Cloud read-only providers carry the same observation; failed refresh hides stale configuration and preserves reload focus. `useLoyaltyPrograms`, `useLoyalty` and `useLoyaltyReceipt` use actual browser-safe descriptors and perform no point writes or automatic recovery.
+
+`./testing` supplies actual installed fresh memory-store `loyaltyPortFixture`, scoped `loyaltyFakeLayer`, a Tag-based port probe and real default tier/perks probes. The fixture uses an actual conserved virtual Shop purchase; its season/refund callbacks are explicitly test authority seams. Normal deactivation revokes escaped services.
+
+
+## Optional Piggy banks
+
+The browser-safe `./piggy-banks` entry exports `definePiggyBank`, the complete
+seven-method `PiggyBanksPort`, exported fill/reset defaults and one shared
+`projectPiggyBank` history projection. Declarations capture ID/version/title,
+an actual registry currency, an exact positive cap, unique `fillFrom` source
+IDs, an unlock `Price` and `reset: 'onUnlock'`. The cap cannot exceed the
+currency's wallet cap. `realMoney:false` refuses real/mixed declarations before
+binding; virtual/free unlocks require no provider credentials. Configuration
+bounds are admission budgets, not measured throughput.
+
+Install through `economyPlugin({ currencies, realMoney: false, piggyBanks: {
+banks, version, fillSource, unlockSource } })`. `fillSource.read` is required
+server authority: accepted tenant/owner, canonical authority/event receipt ID,
+source ID, exact amount and settlement time. `unlockSource.read` is required
+trusted eligibility and price-adjustment authority. Neither source has an
+invented Match/age/provider fallback. Inputs and receiver methods are captured
+before lazy Effects; getters refuse without invocation. Application code owns
+receipt authenticity, revocation and source invalidation.
+
+Canonical fill custody is tenant + logical bank + authority + receipt ID,
+independent of request nonce, source alias or submitted owner. Each player's
+accepted reward needs its own canonical receipt ID: a shared Match ID alone
+cannot identify multiple players' rewards. Rebinding one receipt to another
+owner, even after erasure, conflicts. Only trusted system/allowed-service calls
+can `fill` or `rebuild`; players never submit amount, fill state, Match result
+or reset state. `defaultPiggyFill` grants at most accepted amount and remaining
+cap; named custom fill rules may narrow that envelope only. A fill at cap records
+zero delta and consumes its receipt permanently; replay after reset cannot
+create delayed value.
+
+Four borrowed SQL roles own tenant fences, immutable bank definitions, subject
+fences/end count and accepted events. Complete ordered accepted fill/unlock
+history is available-value/cycle truth and rebuild source; no mutable fill
+cache exists. Durable end count refuses a missing tail. Per-bank sequence,
+monotonic time, owner/definition/evidence and exact arithmetic are checked.
+The first admitted logical bank ID fixes its complete normalized definition,
+registry and rules version; changing them under that ID conflicts. Use a new
+bank ID or an explicit application migration. Live content evolution and
+archival migration are unfinished.
+
+Player `unlock` sends observed bank ID/version/digest, original request ID and
+optional virtual currency only. Eligibility, price and reset callbacks run
+outside replayable SQL. Actual prepared wallet debit, wallet grant, accepted
+reset and receipt commit in one exact-store group using the existing wallet
+writer. Failure rolls back payment and accepted reset/grant together; pending
+wallet admissions may remain. Default reset grants all available value and
+retains zero; a named custom reset retains a remainder and grants only the
+difference, preventing double credit. Current prices are declarations, not
+pinned personalized quotes. Real settlement is explicitly refused by this
+writer; enabling the global money switch supplies no provider implementation.
+
+Accepted original fill/unlock retries and owning `receipt`/`rebuild` read only
+historical SQL, without row seeding, current declaration/clock/source/slot or a
+fresh transfer. `not-observed` is nonterminal, never proof of rollback. Privacy
+works after declarations change: export returns owning bank/evidence/receipt
+history; erase clears owner/body/digest, retains custody, fences and end count,
+and preserves shared definitions. Wallet and other destinations use their own
+privacy hooks. Merge, retention and complete cross-system forensic reconciliation
+remain open.
+
+Complete `piggyBanks.service` replacement captures all seven methods and requires
+explicit nondefault version/content plus actual nonempty
+`querySources.list/receipt` tables. It owns schema/SQL/CDC/source authority/privacy;
+there are no default roles/bounds/source/clock/strategy options or fallback.
+Default SQL Piggy banks refuse a replaced root wallet because they need its
+actual prepared writer. A complete replacement pair may supply its own service.
+Default query sources can add actual app fact invalidation tables.
+
+The installed player queries/actions and `usePiggyBanks`, `useUnlockPiggyBank`,
+`usePiggyBankReceipt` hooks are browser-safe intent/observation paths. There is
+no player fill/rebuild RPC. Four inspect layers and EN/DE panel expose backend,
+version, slots, redacted configured caps/source counts, exact conditional roles
+and SQL bounds or app ownership. No private fills, balances, events or receipts
+appear. Automatic filling, real settlement, durable client recovery and GM
+capabilities remain false. Failed refresh hides stale observations while
+retaining reload focus.
+
+`./testing` supplies a fresh installed `piggyPortFixture`, scoped
+`piggyBanksFakeLayer`, actual Tag probe and default/override fill/reset probes.
+Fixtures use actual conserved wallet transfers; fill/eligibility are explicitly
+named test authority seams.
+
+
+## Personalized, Flash and Bundle merchandising
+
+`./offer-policies` exports browser-safe `definePersonalizedOffers`,
+`defaultPersonalizedOfferSelector`, `resolvePersonalizedOffers`,
+`defineFlashOffer`, `defaultFlashTriggerPolicy`, `resolveFlashOffer`,
+`defineBundle` and `projectBundleValue`. These capture actual normalized Shop
+content and the app currency registry. All `Price` declarations retain the
+global real-money admission; `realMoney:false` supports virtual/free rules
+without credentials and refuses real/mixed content. Enabling real references
+never installs provider settlement. These rules introduce no tables, parallel
+Shop/wallet writer, automatic Tick read or per-player state RPC.
+
+A personalized pool declares ID/version, bounded slots, complete offers and
+play-style affinity tags, plus explicit rotation anchor/duration. Trusted
+context supplies canonical tenant/key, owned item IDs, play styles and time.
+The default ranks unowned item kinds and matching declared styles, then uses
+stable identity/rotation tie-breaking. Declaration order does not determine
+selection. Rotation windows are half-open. A named selector override may choose
+only unique declared offers within the slot bound; unknown/duplicate/excess
+outputs refuse. Inputs and outputs are detached before lazy use. Canonical
+identity across guest upgrade/merge and coherent fact snapshots belong to the
+source; selection is not persisted exposure or account identity authority.
+
+A Flash declaration captures one immutable one-time Shop offer, accepted trigger
+kind and bounded duration. It forces single quantity/per-player lifetime one-time
+limits; original Shop counters own once-only purchase. The trusted trigger
+receipt includes canonical authority/event, tenant/owner, trigger kind and
+accepted timestamp. Foreign, future or mismatched receipts refuse. The window
+starts at that recorded time, is intersected with declaration availability and
+never restarts from a refresh clock. The exported trigger default is replaceable
+by a named narrowing slot; extending its envelope refuses. Missing explicit
+trigger is unavailable, not fabricated eligibility. Event receipt durability,
+revocation and selection of the original trigger remain source responsibilities.
+A new window per later event is not a built-in rotation policy.
+
+`offerPolicyContextSource` accepts optional `personalized`, `flashOffers`,
+`personalizedSelector`, `flashTrigger` and explicit nondefault `policyVersion`.
+Use that identity for the owning Shop rules version too. The required existing
+facts source adds `personalization: { ownedItemIds, playStyles }` for pooled
+offers and `flashTriggers: [{ flashId, trigger }]` for Flash offers. An explicit
+null trigger means no window; omitted required records/facts refuse. Source
+methods retain private receivers and getters refuse. Eligibility narrows the
+existing app eligibility and composes with Starter/experiment rules. Both the
+owning offer query and purchase use this same policy through ordinary Shop;
+accepted original retries preflight historical SQL before current facts/clock,
+even after expiry. No client ownership/style/trigger/window or amount is trusted.
+
+`defineBundle({ offer, parts: [{ offer, qty }], showValue: 'sumOfParts' })`
+requires parts to reproduce exactly the bundle's actual item/currency grants;
+missing/duplicate/self-referential/mismatched parts refuse. Unit-price evidence
+for `projectBundleValue` includes each part's ID/version, source reference,
+observation time and normalized price. All parts must be represented once, with
+explicit maximum age; stale/future/mismatched or amplified prices refuse.
+The actual bundle price is admitted within its declaration too. Only matching
+virtual currencies or real currency references are summed; absent comparability
+produces no comparison, never an exchange rate. BigInt sums can exceed individual
+SQL-wallet BIGINT bounds. `saving` is signed, so a more expensive bundle returns
+a negative difference. Sum-of-parts display is not fabricated anchor-price
+history, a pinned quote or legal/provider price verification.
+
+`./server` adds `bundleValueFromShopReceipts({ shop, bundle, currencies,
+version, maxPriceAgeMs }).read(subject, { at, bundlePrice, originals })`.
+It captures the owning receipt method, checks verified own Subject and full
+part content/rule digest, and reads accepted single-unit free or single-currency
+virtual originals. Accepted price/time/order references supply the value;
+missing/pending/future/stale/foreign/changed originals refuse. This adapter
+accepts no real/mixed or multiple-alternative unit declarations. It reads no
+current source/clock and creates no purchase or table. Purchase the bundle itself
+through ordinary Shop. Verified refund state, provider/current-store prices,
+atomic pricing snapshots and withdrawal/anchor history remain open.
+
+The existing four-layer Shop configuration continues to label an explicit custom
+context source; durable rotation/provider/LiveOps installation flags remain
+false. These helpers do not install a new configuration page, player countdown,
+comparison component, exposure event/ledger or automatic refresh. `./testing`
+exports actual default/override selector and trigger probes.
+
+
+## Shared wallet spend limits and complete-tail custody
+
+`./spend-limits` exports captured currency-specific daily/monthly/minor rules,
+`defaultSpendLimitPolicy`, `resolveSpendBudget`, `utcSpendWindows`, `projectSpend`
+and `assertSpendBudget`. Install `spendLimits: { limits, source, version, policy? }`
+on the ordinary `economyPlugin` or `dataStoreEconomy` options. Limits use exact
+nonnegative integer amounts; null means no configured cap. Minor caps are
+intersected with general caps. Policy version must be explicit and nondefault.
+Named custom policy can only narrow caps and permission. No exchange rate or
+cross-currency total is invented. Only declared limit currencies are covered.
+
+Required `source.read({ tenantId, ownerId, ownerKind, currency, at })` returns
+those exact scope fields, actual `allowed`/`minor` facts, `observedAt`, optional
+parent daily/monthly caps and optional `blockedUntil`. Foreign/future/malformed
+facts refuse; no adult, age or parental-consent fallback exists. Private source
+receivers are captured and accessors refuse. Author source/policy callbacks run
+outside replayable SQL. Fact freshness, revocation and atomic changes of an
+external parental/profile system remain source responsibilities; a timestamp
+field alone is not verification. A block timestamp is a generic restriction,
+not a statutory cooling-off, consent, cancellation or refund implementation.
+
+The existing prepared wallet writer owns the debit check under its ordinary
+subject/currency fences. Shop, paid Crafting, Codes, Containers, Subscriptions,
+Piggy unlocks and server transfers using that actual wallet participant share
+this guard; there is no new Shop wrapper or separate counter cache. Complete
+accepted owner/currency postings and their real paired transfer receipts supply
+spend truth. UTC days and calendar months are half-open; credits/refunds do not
+silently restore consumed allowance. Exact totals are recomputed in the SQL
+commit callback and compared with captured policy, so multiple units in one
+transaction cannot use the same remaining budget twice. Rejection rolls back
+all accepted values/postings/counts/receipts in the group; pending admissions may
+remain. Accepted original retries return before current source/clock/policy.
+
+The existing subject role now retains `entriesCount` for the whole owner's
+ledger across currencies. Each accepted wallet posting increments it in the same
+transaction. Writer, audit/rebuild and unerased privacy require a complete
+bounded owner history with that count; a deleted tail is refused rather than
+rebuilding/spending from a prefix. `maxLedgerRows` therefore bounds complete
+owner history, including all currencies. Erasure keeps the count and permanent
+fence while removing owning fields; shared financial values remain under the
+existing privacy policy. Rebuild repairs materialized wallets, never a missing
+source ledger/count. Missing/invalid count is not automatically inferred from a
+potentially incomplete history.
+
+A fully replaced root wallet refuses default `spendLimits` options and owns its
+own debit/source/SQL/privacy contract. Default configuration needs no extra SQL
+role or secret and works with virtual currency. Provider payments, cross-Store/
+Stripe real-money aggregation, debt/refund/withdrawal policy and complete legal
+parent controls remain open. These options do not grant a player transfer route.
+
+All four inspect layers and EN/DE section report configuration only: rules
+version, policy/source, UTC period, complete-history budget and configured
+currency/minor caps. No owner, actual minor status, parental facts, spend totals,
+ledger or provider references appear. Default SQL root required; unknown/private
+extras, relaxed minors and claimed provider/cooling/parent UI capability refuse.
+Existing read-only host providers/reload/error/focus are reused; failure hides
+stale caps. Provider/cooling/parent UI installation flags remain false.
+
+`./testing` exports actual default/override policy probes, fresh installed
+`spendLimitsPortFixture`, scoped `spendLimitsFakeLayer` and actual `EconomyPort`
+Tag probe using the same writer. Named fixture age/parent facts are test seams;
+normal deactivation revokes escaped wallets.
+
+## Trade intentions and replaceable contract
+
+`@voltro/plugin-economy/trades` contains captured `defineTradeRules`,
+`tradeProposeIntent`, `tradeAcceptIntent`, `tradeCancelIntent`,
+`resolveTradeEligibility`, `resolveTradeTax` and the full eight-method
+`TradesPort`. The Tag alone installs no player routes or panels. The trusted four-role SQL
+adapter is described below.
+
+A proposal selects immutable item instance quantities and declared game-currency
+consideration, target (or public target `null`), bounded lifetime and request ID.
+Those terms never establish ownership or balances. Acceptance sends only the
+observed trade ID/digest and request ID. Cancellation sends only ID/request ID.
+Unknown player state and duplicate assets refuse. Real-money trading has no
+channel. The actual owning service must bind the admitted terms and original
+lifetime to durable custody before producing a receipt.
+
+Trusted participant facts are tenant/owner-bound, include explicit permission,
+TrustScore and actual item quantity/tradability/expiry/lock/reservation identity.
+The default permits an already locked item only for this exact trade reservation;
+foreign locks refuse. TrustScore has to come from the actual sanctions authority;
+this module never invents it. Eligibility and named overrides can only narrow
+permission, target, lifetime, ownership and availability. The adapter must reread
+actual materialization under transaction fences; these facts are not a lock.
+
+Default tax deducts the configured basis points from the receiver's gross amount,
+rounding upward with exact integers. Gross equals net plus tax; an override may
+reduce the declared tax only. The same-writer Wallet participant below owns the
+actual net/tax sink pairs; the durable Trade service below binds that projection to
+reservations, transfer, expiry, original replay and owner privacy. A tax projection does not move or mint value.
+
+`./testing` exports `tradeFixture`, actual default/override
+`tradeTaxSystemFixture` and `tradeEligibilitySystemFixture`. Installed Trade
+Escrow/Inventory binding, owning SQL journal, replacement/scoped Layer, hooks,
+player RPC and four inspect layers are described below. Automatic expiry, client
+journal/components, marketplace search/fee and native parity remain open.
+
+## Same-writer game-currency Wallet Escrow
+
+Default `EconomySqlService` and the installed `economy.economy` facade expose
+`prepareEscrowReserve`, `prepareEscrowRelease`, `prepareEscrowSettle`,
+`prepareEscrowTaxSettle` and read-only `escrow`. Participant/input/observation
+and `WalletEscrowSettlementReceipt` types are exported from
+`@voltro/plugin-economy/server`. These require trusted system or explicitly
+allowed-service authority. The four-method request EconomyPort stays unchanged.
+Replaced root wallets cannot borrow the default SQL participant. The facade
+captures inputs without invoking getters and refuses after normal deactivation.
+
+Reserve takes owner, tenant, permanent reservation ID, declared game currency
+and exact positive amount. The existing prepared Double-Entry writer debits
+available wallet currency and credits the canonical per-owner/reservation/
+currency system Escrow account. Only a private same-writer capability can use
+`escrow.` system accounts; ordinary `transfer` and `prepareTransfer` refuse
+minting or draining that namespace, including `escrow.tax.`. Actual key/digest
+generation is shared. Spend/minor/parent limits apply to the reserve debit;
+release never restores period allowance. No provider or room tick I/O is used.
+
+Nullable server-only transaction `escrow` custody binds immutable reserve terms
+and the accepted close mode, opaque target fence and actual receipts. Reserve
+postings/custody and closing postings/custody each commit in one exact-store
+group. Release returns the whole amount; ordinary settle pays the whole gross
+to a different wallet. Tax settle takes an explicit nonnegative exact `taxAmount`
+and optional reserved-prefix `taxAccountId` (default `escrow.tax.default`). The
+Trade service must derive that amount through `resolveTradeTax`; this trusted
+participant does not invent a tax rate. Gross equals net plus tax. Net is an
+actual wallet payout; positive tax is a separate actual Double-Entry system
+pair to the bound sink. Both use the existing writer. No alternate wallet or
+financial source is installed.
+
+`WalletEscrowSettlementReceipt` reports gross/net/tax and actual nullable
+`payout`/`taxReceipt`. Tax zero has no tax receipt. Tax equal to the entire
+reserved amount has no payout receipt or recipient wallet posting. No zero-value
+or synthetic financial receipt is fabricated. Recipient admission/privacy fences
+still apply. Recipient cap checks net; payout, tax, custody, counts and accepted
+receipts roll back together. A failed preparation may leave pending admission
+rows; pending opposite child intents are not evidence of a paid close.
+
+Release, gross settle and tax settle share one permanent closing identity.
+Deterministic owner/currency/reserve fences and actual paired evidence admit
+only one target/mode/tax/sink. Conflicting retries refuse. Tax-zero and gross
+settle return the same actual payout original. Accepted retries precede current
+clock/spend callbacks; original reserve after close never resets or re-debits.
+Missing accepted custody/close marker, wrong amount/account/owner/time/reference
+or absent paired evidence refuses instead of reopening or inferring payment.
+The bounded prepared-unit budget applies to all descendants. Erased source or
+recipient refuses execution; originals do not bypass privacy fences. No partial
+close, FX, fee or real-money trading is performed.
+
+`escrow` returns `not-observed`, `held`, `released` or `settled` after validating
+custody and real fund/payout/tax pairs, without seed, clock, sources, repair or
+writes. Accepted observations carry nullable `closingReceipt` and `taxReceipt`.
+Ordinary complete Double-Entry history/count rebuild remains wallet truth.
+Missing immutable Escrow custody is refused. Source-owned close observation can
+survive recipient erasure using original receipts and retained redacted financial
+pairs. Opaque fences are pseudonymous, not a legal anonymization claim.
+
+Existing user/guest export includes own `escrows` only when present. Owning erase
+clears Escrow custody/receipts/digests, wallet identity and paired reference/actor
+fields, including the source-owned system-only tax transaction. Financial deltas
+and permanent owner fences remain. Later reserve/close cannot recreate an erased
+owner. Unsettled erased funds stay inaccessible; refund/disposition, guild
+lifecycle, arbitrary actor/reference erasure and legal retention require explicit
+policy. Flow reports show wallet-boundary `escrow.*` sources/sinks, not a newly
+minted supply claim. Complete Escrow/tax analytics classification remains open.
+
+The written `realMoney:false` path needs no provider credentials. Inventory's
+four inspect layers retain `tradingInstalled:false`; these supporting
+participants do not install a player Trade service. Installed Trade
+binding/RPC/four panels are described below. Sanctions/eligibility, automatic
+expiry, components, replacement/scoped port conformance, recovery/consent and
+templates remain open.
+
+## Atomic fresh counterparty and Trade Escrow composition
+
+`EconomySqlService.prepareEscrowReserveTaxSettle` and the default-only revocable
+facade capture `WalletEscrowReserveTaxSettleInput`. They reserve the exact fresh
+amount and settle its net/tax in one actual SQL group. The returned
+`WalletEscrowFundedSettlementReceipt` contains real `reserve` and `settlement`
+receipts. Accepted originals precede current callbacks; changed
+amount/target/tax/sink refuses. No separate wallet writer or second database is
+used.
+
+`./server` exports `tradeEscrowParticipant` and its structural types. It captures
+immutable trusted tenant/trade/proposer/offered/requested game-currency/item
+terms and the actual prepared Wallet and optional Inventory participants. The
+three methods `prepareReserve`, `prepareRelease`, `prepareExchange` require
+trusted system/explicit service authority and a mandatory exact-store prepared
+SQL admission. That admission belongs to the durable Trade writer and actual
+sanctions/eligibility authority. It is not optional, a player payload or a new
+clock/source check inside a replayable SQL callback. It must fence and revalidate
+the current proposal/expiry/participant/consent/eligibility state. The helper does
+not fabricate those facts or a durable Trade journal.
+
+Reserve locks the proposer's actual selected items and moves actual available
+currency to its original Escrow. Exchange requires existing offered custody
+with the exact selected quantities/amounts. It transfers original or split items
+and closes offered currency; requested items and currency use compound fresh
+reserve/transfer and reserve/net/tax participants in the same group. Actual
+`resolveTradeTax` captures exact deductions outside SQL. Release frees only the
+proposer's original offered holdings. No parallel asset writer, new SQL table,
+real-money channel, exchange rate or newly minted Trade value is introduced.
+
+The whole group includes required admission and every prepared descendant.
+Failure rolls back both owners' item/lock/history and wallet/fund/payout/tax/
+custody/receipt effects together; pending admissions can remain. Exact-store
+mismatch and work-budget overflow refuse before commit. Currency-only and
+empty one-sided legs are explicit; items require the actual Inventory participant.
+The normal per-unit recipient caps/capacity still apply in execution order;
+final-position capacity/netting for full inventories is not inferred. This
+fresh helper refuses already transferred/released offered custody. The durable
+Trade writer must return its accepted original before invoking it again.
+
+The test admission exercises actual owner/store fencing only; it is not
+production sanctions, consent or Trade persistence proof. These fixtures use
+actual existing writers, real rollback and exact tax projection.
+
+Installed lifecycle/Tag/RPC/four-layer binding of the durable eight-method
+`TradesPort` is described below. Expiry/recovery workflow, actual sanctions source,
+marketplace/gifting, player components, participant conformance and templates remain open.
+Inventory's existing `tradingInstalled:false` is retained. Trusted asset
+composition alone does not install player trading or complete `realMoney:false`.
+
+## Durable SQL Trade adapter
+
+`@voltro/plugin-economy/server` exports `dataStoreTrades`, `TradeStoreOptions`,
+`TradesSqlService` and four `tradeTables` roles: tenant fence/accepted-trade count,
+subject fence/accepted-operation count, proposal/closing custody and permanent
+request operations. The adapter implements all eight `TradesService` methods
+and a separate trusted `expire`. The request port stays eight methods.
+This is a trusted raw adapter; `economyPlugin` does not install it, its tables,
+Tag, player RPC or panels yet. Existing `tradingInstalled:false` stays accurate.
+
+Options require declared game currencies, explicitly versioned Trade rules,
+actual same-store prepared Wallet/optional Inventory participants and
+`TradeAuthoritySource`. `authority.read` provides actual tenant/owner-bound
+permission, trust score and inventory facts. `authority.prepare` returns a
+required prepared SQL admission that revalidates those facts and owns actual
+revocation/eligibility/consent/expiry fences. Both callbacks run outside replayable
+SQL; the returned unit executes inside the Trade group. No default trust score,
+parental consent, sanctions adapter or permitted actor is fabricated. The named
+`eligibility` override only narrows the existing default Trade policy. An
+application source must integrate its real authority; fixture seams are no proof
+of that integration or of commit-time expiry freshness.
+
+Proposal inputs are detached intentions; no balance, ownership or accepted-state
+payload is accepted. `captureTradeProposeIntention` captures pure bounded wire
+shape. An accepted original is compared before current currencies/rules/source/
+clock admission. Fresh proposals still validate actual declarations and bounds.
+Immutable terms include target or public target null, original lifetime,
+currencies/rules and exact captured tax projection. Offered items and currency
+are held through the actual existing writers in the same group as proposal
+custody and request receipt. Target privacy fences apply. Public proposals do not
+fabricate an unknown accepter; marketplace/listing fee/search remains separate.
+
+Views disclose rule version and each offered/requested gross/net/tax, with
+server-derived nullable accepter ID. The digest binds original terms and tax.
+Accept sends only that trade ID/digest/request ID. Actual participant facts and
+prepared authority admission must permit the original lifetime/target/items.
+The same Trade tenant/owner fences admit one permanent closing mode/participant;
+both actual Escrow legs, taxes, journals/counts/custody and Trade receipt commit
+together. Cancel releases the proposer holdings without fresh eligibility facts.
+Trusted `expire` uses one canonical request after the captured deadline. No timer,
+cron, workflow scheduler or automatic cleanup is installed by this raw adapter.
+
+Matching accepted retries validate SQL custody and actual original Inventory and
+Wallet evidence before current callbacks, including when the winner commits
+during another call's preparation. Changed kind/terms/digest/target or conflicting
+close refuses. Missing accepted operation/trade tail, original custody or paired
+asset evidence refuses instead of reseeding or reopening. Permanent accepted
+markers distinguish erased pending admissions from accepted trade counts;
+request/owner sequences retain a complete bounded accepted tail. Pending requests
+are not accepted value. Whole tenant/owner work exceeding the configured budget
+refuses. Execution-order asset caps/capacity remain conservative.
+
+`mine` is tenant/participant scoped; it does not reveal all public listings.
+`receipt` is actor/request scoped and read-only. `rebuild` repairs only mutable
+Trade state from complete accepted proposal/closing/request custody and validated
+asset evidence; it never repairs missing history, redebits or re-grants assets.
+Wallet/Inventory own their materialization rebuilds. No current source callback
+or hidden cache becomes truth. Complete runtime CDC/query invalidation is still
+part of the installed binding.
+
+User/guest export includes owned/targeted/accepted Trade custody and own requests.
+Erase clears related proposal/closing and all copied counterpart Trade receipt
+bodies, own identity and pending payloads, preserving permanent opaque fences/
+counts/markers and financial asset truth in the owning plugins. Repeated erase
+remains valid. Unsettled erased funds/locks require explicit disposition and
+coordinated owning-plugin privacy policy; this hook invents no refund or transfer.
+A partial peer Inventory erase can leave no full peer receipt for Trade proof;
+that incomplete proof is refused until coordinated privacy completes. Opaque
+keys are pseudonymous, not legal anonymization or retention decisions.
+
+Native sources apply all four actual table roles and use independent participant
+pools. Shared canonical JSON serialization reuses the existing Shop
+implementation so JSON key order does not change declaration hashes.
+
+Installed lifecycle/Tag/complete replacement/player query/action/four-layer
+binding is described below. Events/Mixins, actual sanctions/consent authority,
+expiry/ recovery workflows, public marketplace/gifting, player components and
+templates remain open.
+
+## Installed Trade system
+
+`economyPlugin({ currencies, trades: { rules, authority, inventory } })` now
+installs the actual eight-method `TradesPort`, conditional four Trade table roles,
+normal bind/deactivate/export/erase hooks and five browser-safe player routes.
+`authority` is required for the default SQL adapter: its real scoped facts and
+exact-store prepared revalidation unit must own sanctions, trust, consent and
+stock freshness. No default permission or production sanctions source is supplied.
+The installed Inventory plugin's `inventory` facade can provide the actual item
+participant; omit it only for currency-only trades. Default SQL Trades over a
+fully replaced root wallet refuses before binding. No room/tick or uninstalled
+boot path is added.
+
+The optional `trades` configuration inherits declared currencies, root clock and
+trusted service names. Explicit `rules.version` is required. Named `eligibility`
+and `taxPolicy` slots reuse actual defaults and may only narrow admission/tax.
+`maxHistoryRows` bounds the complete tenant Trade history and each owner request
+history; it is a configured refusal budget, not capacity evidence. The shared
+`resolveTradeStoreOptions` captures participants/configuration before binding,
+including private method receivers, and rejects getters without invoking them.
+
+A complete `trades.service` replacement must implement all eight owning methods,
+supply versioned `rules` and actual `querySources: { mine, receipt }`. It owns
+schema, authority, receipts, CDC and privacy. Default authority, item participant,
+clock, work-bound and policy options are refused with a replacement. No default
+Trade roles, SQL budgets or fallback are installed. The plugin still applies
+verified subject, own intention and trusted rebuild guards to captured methods;
+normal deactivation revokes escaped/lazy facade calls. In-progress operations
+are not claimed to be cancelled by deactivation.
+
+Player RPCs are `economy.trades.mine`, `economy.trades.receipt`,
+`economy.trades.propose`, `economy.trades.accept`, `economy.trades.cancel`.
+`./web` exports `useTrades`, `useTradeReceipt`, `useProposeTrade`,
+`useAcceptTrade`, `useCancelTrade`. Proposals choose terms/target/lifetime/request;
+acceptance chooses the observed original digest/request; cancellation chooses
+trade/request. No balance, owner, permission, tax or resulting state is accepted.
+Views disclose original gross/net/tax, rule version and server-derived accepter.
+Wire schemas validate exact amounts and coherent tax/target/state disclosure.
+Queries observe original SQL plus actual asset receipt sources; explicit app fact
+sources may extend default sources. Currency-only installation omits Inventory
+sources. No client recovery journal or automatic retries are provided by hooks.
+
+`plugin.economy.expireTrade` is trusted server-only for the default adapter. It
+uses the same permanent closing identity and actual original release; before the
+captured expiry it refuses. A full replacement exposes no synthetic expiry
+method/fallback. No player expiry route or automatic expiry scheduler is installed. The explicit
+app-owned batch/schedule factory is described below.
+
+Server `/status`, Shared UI, Cloud decoder/proxy and the Local read provider
+share strict `tradesInstalled`/nullable `tradesSystem`, actual backend/rule/slot/
+authority/item participant/budget and exact conditional table roles. The bilingual
+configuration section shows configured tax, lifetime and minimum trust only;
+never player facts, subjects, terms, operations, assets or receipts. Replacements
+report app-owned authority/items, custom slots and null SQL budgets. The existing
+reload/failure/focus/provider path is reused; no new GM write capability appears.
+Public marketplace, automatic expiry, GM actions and client recovery remain false.
+
+`./testing` exports fresh installed `tradesPortFixture`, scoped
+`tradesFakeLayer` and an actual `tradesPortSystemFixture` probe over the same
+wallet and Inventory writers. Named permission/trust fixture seams are not
+production sanctions or consent. Full generic `systemContractConformance`,
+Events/Mixins, production sanctions/consent/freshness, automatic
+expiry/recovery, marketplace/ gifting, coordinated erase/disposition, player
+components and templates remain open.
+
+## Explicit bounded Trade expiry schedule
+
+Default `TradesSqlService.expireDue` and installed `plugin.economy.expireDueTrades`
+accept trusted server subjects plus `{ tenantId, maxTrades? }`. `maxTrades`
+defaults to 1000 and is a refusal budget within the existing complete-history
+bound. A user or inactive/replaced/unconfigured default system refuses. Inputs
+and the runner's private receiver are captured before lazy execution. No player
+batch/expiry route, tick read or new SQL table is introduced.
+
+The runner captures its clock outside SQL, reads the complete bounded tenant
+Trade snapshot, validates permanent accepted counts, proposal/closing/receipt
+metadata and distinct owner tails, then selects only proposed deadlines at or
+before that captured instant. The same captured snapshot and distinct-owner
+validation are reused during selection. Erased custody stays frozen and is not
+reopened. More due trades than `maxTrades` refuses before the first close;
+missing history or malformed metadata cannot be treated as an empty backlog.
+There is no unproved pagination cursor, archive or repaired-history shortcut.
+
+Each selected trade closes through actual existing `expire` and original asset
+release in its own complete transaction. A competing accepted/cancelled/expired
+closing is counted only after re-reading valid durable Trade custody and actual
+asset evidence; a still-open or erased/corrupt failure stays failed. An
+interrupted batch may have committed earlier individual closes: the entire
+firing remains failed, and explicit retry selects remaining original custody.
+This is not a batch-wide transaction or exactly-once cron delivery claim.
+
+Successful output contains counts and `capturedAt` only: `scannedRows`,
+`dueTrades`, `expiredTrades`, `alreadyClosedTrades`. `expiredTrades` counts
+matching original expiry receipts observed by this invocation; parallel jobs
+can both observe one receipt. It does not mean a count of fresh financial
+writes. Repeated invocation after closure sees no due trade. No owner, terms,
+request identity, asset or receipt body is returned by the batch report.
+
+`./server` exports ordinary app-owned `tradeExpirySchedule({ tenantId, runner,
+maxTrades?, name?, cron?, timezone? })`. The `runner` can be the installed
+`plugin.economy` facade. Default cron is `* * * * *` in UTC; registration is
+explicit through the existing app schedule mechanism. The handler uses a
+server system subject, invokes the real runner and fails the firing for errors
+or inconsistent counts. The plugin itself registers no automatic job, so the
+configuration panel still reports `automaticExpiryInstalled:false`. Full
+replacements receive no default batch/expiry fallback.
+
+Accepted owner-history validation now also checks every operation's tenant,
+owner key/identity, admission, kind/state, permanent request ID/digest and exact
+receipt shape even when the requested original belongs to a different trade.
+Per-trade operation selection reads the complete bounded set and selects
+accepted sequence markers; pending opposing requests do not hide a later
+accepted receipt behind a fixed four-row prefix. No missing tail/count is inferred.
+
+The direct schedule-body fixture is not execution by the scheduler engine or a
+durable cron/crash proof.
+
+## Explicit client Trade intention recovery
+
+`./web` exports `createTradeRecovery`, `browserTradeIntentionJournal`,
+`captureTradeIntention` and the public journal/slot/reference/transport/recovery
+contracts. The transport supplies the three installed propose/accept/cancel
+Actions; propose receives canonical string amounts, suitable for the wire schema.
+A caller supplies a stable app plus authenticated tenant/account scope without
+credentials and updates it on every account/session/target change. The server
+still derives real owner/tenant from its authenticated Subject; a client scope
+is not proof of authority.
+
+A saved `TradeIntention` is one of `{ kind:'propose', input }`,
+`{ kind:'accept', input }`, `{ kind:'cancel', input }`. Only captured intentions
+are persisted, with version1 and scope. Selected item references, quantities and
+consideration are intentionally part of proposal recovery, never statements of
+ownership/balance, player facts, trust, secrets or received asset state. The
+browser namespace is `voltro:trade-intention:v1:<scope>` with a configured
+32768-character refusal bound. It stores one unresolved intention per scope;
+no expiry deletes an uncertain request and no new nonce replaces it.
+
+`begin` captures and requires a matching storage read acknowledgement before
+transport is possible. `retry(original)` acquires the actual cross-tab Web Lock,
+rechecks saved scope/operation/terms/request and holds that lock through response
+and settlement. It sends only the saved original, never automatically replays
+or invents a request ID. Failure keeps the acknowledged record. Every
+`selectScope` invalidates queued/in-flight continuations, including switching
+away and back; a late accepted response cannot clear the old original under a
+new session. Explicit observation can later reconcile that original.
+
+`observe` accepts detached `TradeObservation`; not-observed stays unresolved.
+Only a matching original receipt may clear. Proposal receipts must match target,
+complete offered/requested terms and original duration with state proposed;
+accepted receipts match trade/digest with accepted state; cancellation matches
+trade with cancelled state. All check matching request/observation identity and
+complete coherent gross/net/tax, lifetime, target/accepter and rule shape.
+A proposal's original receipt remains proposed even if its current trade later
+closes; a current list snapshot is not the proposal operation receipt. Missing,
+changed, malformed or erased evidence never grants dismissal authority.
+
+Pure `captureTradeView`, `captureTradeReceipt`, `captureTradeObservation` in
+`./trades` reuse one shape validator across RPC, owning SQL request history and
+client recovery. They reject getters/unknown fields and validate disclosure;
+shape validation is not server asset/permission proof. Missing owner history
+cannot become an empty accepted tail. Shop and Trade now use one internal
+acknowledgement/scope/lock/storage/retry algorithm; Shop retains its public
+contracts, original namespace and domain-specific purchase matching. No parallel
+Shop implementation or alternative financial writer remains.
+
+The caller must provide actual browser storage and Web Locks. Missing capabilities
+refuse; there is no memory fallback. Factory-provided journals must honor the
+same cross-tab and durable acknowledgement contract. Captured journal/transport/
+storage/lock methods preserve private receivers and refuse accessors. Hooks do
+not automatically construct a journal, select identity, retry, or add a player
+screen. The server configuration observation therefore still reports
+`clientRecoveryInstalled:false`; explicit app integration is required.
+
+The deterministic lock/storage seam does not prove actual browser cross-tab,
+storage-event, engine SDK or crash behavior. Player recovery components are
+described below; template/consumer integration, production sanctions and
+consent, gifting/public marketplace and coordinated privacy/disposition remain
+open; no acceptance, capacity or complete virtual-only stack claim.
+
+## Player Trade disclosure and recovery components
+
+`./components` exports `TradeTerms`, `TradeList`, `TradeAcceptDialog`,
+`TradeIntentionRecovery`, their prop contracts and bilingual `tradeUiCopy`.
+They extend the existing semantic UI/dialog/button system and accept app-owned
+source, action, journal and content-label callbacks. No transport, credential,
+financial writer or new visual system is embedded in the components.
+
+`TradeTerms` captures a coherent original server view before displaying proposer
+and counterparty item selections plus gross/net/tax for each game currency,
+including a zero net payout. Unknown or inconsistent disclosure shows an error.
+Instance/currency label callbacks resolve actual app content; the component
+never invents an item identity, price, permission or trust score. Terms are
+original server disclosure, not a live wallet or ownership report.
+
+`TradeList` renders own/targeted/accepted views only for its current `actorId`;
+foreign participant observations and duplicate/invalid views refuse. This is
+presentation scoping, not server authority. A failed or loading source hides
+stale actions. Review/Cancel are guarded by original state and actor selection;
+new review additionally requires an observed lifetime that is still open.
+Deadline display uses the chosen locale, and time is supplied explicitly; no
+hidden server clock or per-tick read is introduced. The source list has a
+configured 1000-view refusal bound, not a support/capacity claim.
+
+`TradeAcceptDialog` uses the existing native modal with labeled title/help,
+both sides and explicit original acceptance intention. Confirmation requires
+matching trade/digest, actor, proposed state, original open lifetime and no
+busy/error/result state. The callback sends only that captured intention;
+the parent acknowledges it through recovery before the actual Action.
+An accepted original is displayed only when request/trade/digest/accepter and
+all immutable terms/dates/rules/taxes match; a late response after the displayed
+deadline remains valid while a new acceptance stays disabled. Close/ESC never
+clears a saved uncertain request. Native stacking/focus behavior needs later
+browser evidence.
+
+`TradeIntentionRecovery` belongs above transient lists, errors and dialogs. It
+checks reference version/expected account scope and captured operation before
+showing an unresolved request; a foreign or unauthenticated scope hides it
+without deleting the durable record. It shows selected proposal consideration
+without inventing tax before a server proposal receipt exists. Recovery reference
+is secondary in a disclosure. Retry and optional receipt-check controls invoke
+only saved original callbacks; there is no dismiss, new nonce or silent storage
+clear. Busy controls remain mounted/focusable with guarded `aria-disabled`.
+Raw exception/provider bodies are not exposed to players.
+
+They use actual installed wallet/Inventory Trade writers and the journal;
+native-dialog methods and storage/locks remain explicit DOM seams, not proof of
+keyboard stacking, responsive/mobile, actual transport or cross-tab browser
+behavior. A complete app session/provider/journal parent integration and
+templates remain open.
+
+## Inventory-backed Trade authority
+
+`inventoryTradeAuthoritySource(store, { permissions, inventory, items })` from
+`@voltro/plugin-economy/server` composes the actual bound Inventory service with
+an explicit `TradePermissionSource`. The permission source must provide both
+`read` and `prepare`; there is no default allowance, trust score, adult status or
+consent. Its read returns tenant/owner-bound `allowed` and `trustScore`. Its
+prepared SQL unit must fence the owning policy records and revalidate those
+captured facts. A read-only Sanctions port cannot fulfill this atomic contract.
+Until that integration exists, leave Trades uninstalled or fail admission.
+
+The helper reads actual own possessions and original reservation evidence.
+Tradability comes from explicitly supplied item contracts keyed by item ID and
+schema version. An unknown contract refuses. Another trade's lock never becomes
+this trade's reservation. The existing actual Inventory/Wallet writers still
+revalidate stock, expiry and conservation inside the same commit; a shaped
+client object or the helper's read alone never establishes admission.
+
+`captureTradeAuthorityAdmission` captures one proposer or two distinct accepting
+participants, the original trade/tenant, phase and open lifetime. The policy
+receives detached permission facts rather than item attributes or author-owned
+arrays. The helper admits its prepared unit against the exact supplied SQL
+store before any writer executes. A foreign-store unit refuses. Policies must
+implement their actual sanctions, consent and privacy fences; the helper creates
+no policy table, automatic sanctions installation or synthetic permission.
+
+The source fixtures contain a clearly named test-only app-policy table and use
+actual borrowed SQL plus Inventory/Wallet writers. Five source scenarios and one
+scenario per six native variants cover custody, revocation between read and
+commit, full rollback, receiver/getter admission, removed contracts, unavailable
+facts and original receipt replay after revocation.
+
+## Actual SQL sanctions in Trade admission
+
+`sanctionsTradePermissionSource(store, sanctions.sanctions.admission())` from
+`@voltro/plugin-economy/server` supplies the required policy for
+`inventoryTradeAuthoritySource`. It calls the actual server-only prepared
+Sanctions capability at enforcement point `trade`, with the Trade writer's
+captured time. Each participant receives real active-measure and conservative
+strike-derived trust checks; no `allowed:true`, trust bonus or policy table is
+invented by the adapter. Receiver-safe methods and detached input admission
+preserve tenant/owner binding. Permission units must belong to the same SQL store
+as Inventory, Wallets and Trades. The returned guarded group revalidates actual
+sanction records atomically with the assets.
+
+Actual `tradeBan`, general bans, insufficient trust, unavailable service, erased
+identity and changed prepared records refuse new acceptance. A participant may
+still cancel an existing hold through the ordinary Trade release path. Accepted
+original proposal/accept receipts remain recoverable before current policies,
+never grant fresh authority. Policy errors retain redacted forbidden/conflict
+semantics across the SQL boundary. Proposal and acceptance acquire policy before
+Trade/asset admission. Additional consent or legal gates require their own real
+prepared policy; this adapter establishes sanctions only.
+
+The `api-economy` source factory now installs actual Sanctions, versioned
+Trades, Inventory and Wallets in one application. Binding supplies the exact
+borrowed store to these helpers; there is no substitute wallet, fake sanction
+service, player balance write or provider credential. An explicit bounded app
+schedule expires held proposals.
+
+
+## Explicit IAP verification foundation
+
+`./iap` is browser-safe and exports
+`defineIapCatalog`, `iapReceiptIntent` and `iapProductsCsv`. A product explicitly
+maps an existing captured Shop offer, channel and consumable/non-consumable/
+subscription kind to the offer's real or mixed store SKU. Duplicate SKU or offer
+mappings per channel refuse. Non-consumables and subscriptions require one unit; non-consumables also require a per-player cap of one.
+The catalog preserves the actual offer grants; it never provisions store products.
+CSV exports identifiers and kinds for console preparation, without receipts,
+reference prices or credentials. A sync-products CLI is not installed yet.
+
+An empty catalog works with `realMoney:false` without provider configuration.
+Nonempty real catalogs and all verification adapters refuse when money is disabled.
+The receipt intent contains only channel, offer ID/version, request ID and bounded
+opaque receipt. Tenant, owner, amount, transaction identity, quantity and payment
+state are not player inputs. Do not log raw receipt evidence.
+
+The server-only `IapVerificationPort`, `iapVerificationPort`,
+`appleIapVerificationPort` and `googleIapVerificationPort` require explicit trusted
+account authority. `IapAccountSource.read` returns the server-owned stable account
+binding for the authenticated tenant/owner and provider environment. It must be
+unique across all tenants sharing an application. Never accept that binding from
+an RPC input. The generic replacement is deliberate server authority responsible
+for authenticity, fresh provider status and account binding; its output shape
+alone proves none of those properties.
+
+Apple uses the official server library with supplied DER trust roots and online
+certificate checks. It verifies the submitted StoreKit 2 JWS, requests its current
+transaction from the App Store Server API and verifies that JWS too. The two
+transaction projections must agree. Bundle, environment, SKU, type and
+`appAccountToken` must match; family sharing, revocation, upgraded subscriptions,
+advanced commerce and malformed data refuse. Production requires `appAppleId`.
+Only Sandbox and Production are admitted; unsigned Xcode/LocalTesting modes are
+excluded. `AppleIapCredentialSource.read` supplies rotated App Store Connect
+signing key/key ID/issuer ID. Missing credentials or verification failures never
+switch provider or fulfill a payment. The upstream contracts are in the
+[Apple library](https://github.com/apple/app-store-server-library-node).
+
+Google reads the fixed authenticated [Products v2 endpoint](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2/getproductpurchasev2)
+using an explicitly supplied server-side service-account OAuth source with
+androidpublisher authority. HTTP has abort/time/byte budgets and refuses redirects.
+A successful purchase must match the server account and exactly one configured
+product. Pending/cancelled, partially refunded, rental/preorder and ambiguous
+multi-line purchases refuse. Sandbox requires an explicit test-card purchase;
+production rejects test purchases. Consumption and acknowledgement observations
+are retained. They do not authorize regranting an already processed purchase.
+Google subscriptions remain separate unfinished work.
+
+`VerifiedIapPurchase` is opaque process-local evidence; copying or serializing it
+loses its verification capability. Transaction custody identity includes channel,
+environment, application and provider transaction, independent of request, tenant
+or owner. Google tokens are hashed, never exposed as transaction IDs. Apple paid
+amounts retain their provider milliunit scale. Google Products v2 supplies no paid
+amount here, so `paid` remains null. Reference prices never fill that gap or produce
+Loyalty spend credit. Evidence alone does not grant assets, record an order,
+establish consent or implement privacy/retention.
+
+The explicit SQL adapter described below now owns durable receipt custody and
+atomic fulfillment. Optional lifecycle/RPC/four-layer configuration binding is
+described below; `paymentsInstalled` reports configuration only. Provider roots,
+credentials, products and sandbox accounts are operator decisions. No capacity
+claim follows from the configured work budgets.
+
+
+## Explicit SQL IAP fulfillment
+
+`dataStoreIap(store, options)` borrows the app store and supplies the four-method
+`IapService`/`IapPort`: redeem, receipt, exportSubject and eraseSubject. It requires
+`realMoney:true`, an immutable operator-owned namespace, matching currencies,
+verification service, mandatory prepared SQL purchase admission, actual prepared
+Wallet/Inventory participants and an explicit source account. It opens no store,
+registers no timer and changes no boot path. `captureIapService` binds all four
+replacement methods, including private class receivers, without executing getters.
+The optional Economy plugin IAP binding described below installs this adapter.
+
+Four server tables own namespace work counts, subjects, orders and global receipt
+custody. The receipt primary key derives from provider application/environment/
+channel/transaction independently of tenant, owner, request and work namespace.
+Pending verified custody binds the original order permanently; aborted groups may
+retain pending admissions, never accepted value. A fresh alias or owner/tenant/
+namespace rebind returns `already_redeemed`. The exact accepted original request
+returns its stored receipt before current provider, clock, policy or participant
+callbacks. Changed intentions conflict. Raw receipt evidence is hashed and never
+stored in order snapshots or exposed in player receipts.
+
+Fresh fulfillment requires opaque verification capability, exact matching currency
+configuration and a prepared `IapPurchaseAdmissionSource`. The application must
+provide actual age/consent/spend authority under its own SQL fences; no permissive
+facts or consent default exists. Namespace, subject and receipt fences, admission,
+actual wallet transfers, catalog inventory grants and accepted order/custody commit
+as one exact-store group. A foreign-store participant, revoked policy, capacity
+failure or malformed returned receipt rolls back accepted state. Fresh evidence
+already consumed or acknowledged refuses; historic originals still recover first.
+Subscriptions refuse here until their entitlement implementation exists.
+
+One-time/per-player, UTC-day and global quantity limits use whole bounded accepted
+SQL history. Non-consumable declarations require a single unit and per-player cap
+of one. Accepted offer/channel/version configuration digests remain immutable even
+after body erase. Accepted offer quantities/days retain global consumption after
+erasure. Namespace and subject row counts detect missing history; exceeding the
+complete work budget refuses instead of scanning a prefix or repairing from a
+partial selection. No process lock or second monetary writer is introduced.
+
+Export includes own pending/fulfilled order observations without raw receipts.
+Erase removes owner links and full order/provider bodies, fences recreation and
+retains permanent receipt custody, counters and minimal quantity metadata. These
+keys are pseudonymous, not an anonymization claim. Wallet and Inventory own
+their separate export/erase hooks; this adapter neither erases those systems nor
+invents refunds, retention periods or disposition of paid assets.
+
+They exercise real Wallet/Inventory writes, original recovery, custody,
+rollback, SQL-policy revocation, erasure and missing-history refusal.
+
+
+## SQL-owned IAP account bindings
+
+`dataStoreIapAccounts(store, options)` implements the server-only five-method
+`IapAccountsPort`/`IapAccountBindingService`: read, observe, prepareBinding, exportSubject and
+eraseSubject. Its real-money/application/channel/environment configuration is
+captured once. `read` captures the server-selected tenant/owner, mints a public
+pseudonymous UUID at runtime and persists one stable binding under the actual SQL
+owner fence. A second process/pool reads that same token. Different owners,
+tenants, applications, environments and channels have distinct records; requesting
+a channel/environment outside the configured service refuses. Tokens are account
+identifiers for StoreKit/Play, not secrets or authentication credentials.
+
+Two SQL roles own account bodies and global token-uniqueness custody. Account keys
+bind actual application/channel/environment/tenant/owner; token custody is global
+within application/channel/environment, independent of tenant. Entropy is captured
+before replayable SQL, never supplied by the player. Erase removes owner/token
+bodies, marks custody erased and permanently refuses recreation. Export returns
+only the selected binding. Retained keys are pseudonymous, not anonymous. Account
+merge, migration, external-token adoption and retention are unfinished.
+
+`IapAccountSource` now requires both read and prepareBinding. Verification evidence
+privately retains its captured account source/token; no account token enters
+player evidence, order snapshots or financial receipts. The default IAP SQL
+writer prepares that binding and puts its exact-store guard before purchase
+admission and asset writes. Account erasure after provider verification therefore
+refuses the fresh commit. Accepted originals are read from their financial SQL
+receipt first and can recover after separate account erasure until order privacy
+removes their body. Do not treat a read-only account lookup as atomic admission.
+Complete account replacements own their real prepared SQL authority and privacy.
+
+Standalone SQL adapters require their own account and financial privacy wiring.
+Storage/account guards use actual SQL; their provider verifier remains a
+deliberate synthetic seam.
+
+
+## Installed IAP readiness, privacy and configuration
+
+`economyPlugin({ currencies, realMoney: true, iap: { version, products, providers,
+namespace, admission, inventory, systemAccount } })` now installs optional IAP.
+The default SQL binding requires explicit immutable version/namespace/source
+account, actual prepared age/consent/spend admission and actual Inventory
+preparation when products grant items. It reuses the installed default Wallet;
+default SQL fulfillment over a replaced root Wallet refuses. Subscription
+products refuse this default installation until entitlement fulfillment exists.
+
+Each provider declares channel, sandbox/production and actual application ID,
+plus a synchronous server `create(context)` factory. Channels are unique; all
+products need a provider and each provider needs products. The captured context
+contains only that channel's actual catalog, currencies, app/environment, clock
+and borrowed-store account registry. Factories return complete initialize/verify
+services. Verified app/environment/catalog/currency evidence must match the
+installed declarations. Provider shape is not authentication authority; use the
+actual Apple/Google adapters or an explicitly trusted server replacement.
+
+```ts
+import {
+  googleIapVerificationPort,
+  type GoogleIapAccessTokenSource,
+  type IapProviderDefinition,
+} from '@voltro/plugin-economy/server'
+
+// Example application identity only; provision the actual app and SKU in the store console.
+export const playProvider = (
+  accessTokens: GoogleIapAccessTokenSource,
+): IapProviderDefinition => ({
+  channel: 'android',
+  environment: 'production',
+  applicationId: 'studio.example.game',
+  create: ({ realMoney, environment, applicationId, products, currencies, accounts, now }) =>
+    googleIapVerificationPort({
+      realMoney, environment, applicationId, products, currencies, accounts, now,
+      accessTokens,
+    }),
+})
+```
+
+Binding constructs adapters without reading credentials or importing the Apple
+SDK. Only configured IAP contributes `onActivate`; it awaits every captured
+provider's required `initialize` before exposing IAP operations. Apple reads and
+validates supplied App Store Connect credentials and constructs its real SDK
+trust verifier. Google reads and admits the supplied server token. These checks
+are setup admission, not proof of remote authorization, token expiry or a valid
+purchase. Every verification reads the credential source again for rotation.
+Missing required credentials or defective roots fail initialization; no unsigned,
+fake credential, automatic provider switch or fallback is supplied. Deactivation
+revokes the facade; a late initializer cannot reopen a deactivated generation.
+
+`economy.economy.iap()` returns initialize/account plus the four-method IapPort
+facade. `economy.iap.account` is an Action: verified own user/guest selects channel
+only, the server persists/returns its public account UUID. `economy.iap.redeem`
+is an Action accepting only `IapReceiptIntent`. Preserve the original request on
+uncertain responses. Do not log raw receipts; retain the Audit plugin's input
+redaction. Neither Action wraps the owning adapters in another transaction.
+`useIapAccount` and `useRedeemIap` are in `./web`.
+
+`receipt` now takes `IapReceiptReference`: channel/offer/version/request and a
+SHA-256 receipt digest, never the raw receipt. `createIapReceiptReference(intent)`
+in `./iap` captures the input before Web Crypto hashing the canonical JSON string
+representation used by SQL. `iapReceiptReference` admits stored references.
+`economy.iap.receipt` and `useIapReceipt` use this read-only hash reference; they
+never verify, seed or grant. Missing/pending observations remain nonterminal;
+a changed reference conflicts. This is not a durable recovery journal.
+
+Installed export composes own account and financial observations. Erase first
+revokes account bindings, then removes financial bodies, before the root Wallet
+hook erases its owner. Destination Inventory keeps its own installed privacy
+hook. The sequence is retryable, not an atomic cross-plugin erase or paid-asset
+refund/disposition policy. Removed account/receipt identities remain fenced.
+
+A complete `IapSystemService` replacement implements initialize/account/redeem/
+receipt/complete/exportSubject/eraseSubject, supplies captured products/version and actual
+receipt query sources, and forbids all default SQL options. It owns provider,
+account, schema, authority, CDC, grants, conservation, activation and privacy;
+there are no default IAP roles, borrowed default Wallet, SQL budgets or fallback.
+Private class receivers work; getters and partial services refuse.
+
+The four configuration layers show exact optional six SQL roles, provider
+applications, product mappings, binding/source/version and work budgets. Full
+replacement has no provider declaration list or default work bounds. The
+`paymentsInstalled`/`iapInstalled` flags report configured receipt fulfillment,
+not provider health or successful purchases. Explicit completion authority is
+reported per channel below. Notifications and refund debt are conditional on the
+explicit optional binding below; subscription entitlements, GM actions and
+installed client recovery remain false.
+
+
+## Explicit provider completion after accepted SQL
+
+`dataStoreIap` now additionally exposes server-only
+`IapSqlService.prepareCompletion(subject, originalIntent)`. This is a read-only
+accepted-original path: own verified subject, exact request/evidence digest,
+fulfilled order, complete accepted body and matching global SQL custody. Missing,
+pending, changed, erased or corrupt evidence refuses. No order is seeded, grant
+replayed, clock consulted or provider called. The result is an opaque
+`AcceptedIapCompletion` capability with order ID only. Raw receipt remains in its
+private captured resolver; JSON/shape copying cannot restore authority. Exercising
+the capability re-reads the owning SQL original, so later erasure/removal refuses
+before provider I/O. This is not an atomic lock spanning SQL and a remote store.
+
+`IapCompletionPort`/`IapCompletionService` has required initialize/complete methods.
+`iapCompletionPort` captures a deliberate trusted server completion authority,
+actual catalog/app/environment/currencies and account source. It admits the real
+accepted SQL capability and current account before provider completion. It does
+not verify a new purchase, fulfill, reverse money or accept player state. Complete
+replacements own actual provider observations; output shape alone proves nothing.
+Private receivers are captured, required getters refused, defects redacted.
+
+```ts
+import { Effect } from 'effect'
+import type {
+  IapSqlService,
+  IapCompletionService,
+} from '@voltro/plugin-economy/server'
+import type { IapReceiptIntent } from '@voltro/plugin-economy/iap'
+import type { Subject } from '@voltro/protocol'
+
+export const completeAccepted = (
+  orders: IapSqlService,
+  provider: IapCompletionService,
+  subject: Subject,
+  originalIntent: IapReceiptIntent,
+) => Effect.gen(function* () {
+  const evidence = yield* orders.prepareCompletion(subject, originalIntent)
+  return yield* provider.complete(evidence)
+})
+```
+
+`googleIapCompletionPort` takes the same operator-owned options as the Google
+verifier. Its credential source is read on every invocation; explicit initialize
+checks setup admission only. Completion reuses the verifier's bounded fixed
+Products-v2 GET. Current owner, application, environment, SKU, quantity, purchase
+time/value and token identity must match the accepted original. Cancellation,
+partial refunds or changed purchase identity refuse before a provider POST.
+Consumables use the official [consume endpoint](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/consume);
+non-consumables use [acknowledge](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge),
+with an empty body or empty JSON respectively. No developer payload, nonce or
+new transaction is minted. Existing terminal provider state needs no POST.
+
+After a successful or uncertain POST, one fresh authenticated GET must observe
+matching consumed/acknowledged state. POST response alone is not completion;
+nonterminal state returns unavailable while accepted SQL assets/custody remain.
+An explicit same-capability/original-intention retry observes current state and
+never grants again or automatically sends a second POST after one uncertain call.
+HTTP uses redirect refusal, abort/time/byte budgets and redacted failures. No
+reference price is converted into paid amount or Loyalty credit.
+
+This standalone port is implemented. Installed completion/RPC and encrypted
+notification/refund binding are described below. StoreKit client finish,
+subscriptions, Steam/Web and full workflow integration remain separate open
+work. Configuration panels report the actual configured completion factory.
+Synthetic HTTP/OAuth fixtures use only newly generated transient test material;
+they are not real Google authorization, sandbox purchase or production evidence.
+
+
+## Installed explicit provider completion
+
+A provider may additionally declare `createCompletion(context)`. Its captured
+initialize/complete service is constructed during binding without I/O, and its
+initializer is awaited during IAP activation. Missing/failed readiness keeps the
+IAP facade unavailable. A channel without completion authority has no implied
+completion fallback. The complete system replacement now requires seven methods,
+including `complete(subject, originalIntent)`, and owns its completion lifecycle.
+
+The installed facade prepares a read-only opaque capability from the exact own
+accepted SQL order, then delegates to the configured channel authority. A
+changed receipt/owner/request cannot finish another purchase. It never redeems
+again, invokes the purchase verifier, grants items or posts Wallet value.
+Deactivation before handoff to the authority refuses. No-IAP applications
+receive no additional activation hook or completion route.
+
+```ts
+import { economyPlugin } from '@voltro/plugin-economy'
+import {
+  googleIapProvider,
+  type IapPluginOptions, type GoogleIapAccessTokenSource,
+} from '@voltro/plugin-economy/server'
+import { Effect } from 'effect'
+
+const installPlayEconomy = (
+  currencies: Parameters<typeof economyPlugin>[0]['currencies'],
+  iap: Omit<IapPluginOptions, 'providers' | 'service' | 'querySources'>,
+  applicationId: string,
+  accessTokens: GoogleIapAccessTokenSource,
+) => economyPlugin({
+  currencies, realMoney: true, iap: {
+    ...iap, providers: [googleIapProvider({
+      environment: 'sandbox', applicationId, accessTokens,
+    })],
+  },
+})
+
+const completeOriginal = (
+  installed: ReturnType<typeof installPlayEconomy>,
+  subject: Parameters<ReturnType<typeof installed.economy.iap>['complete']>[0],
+  originalIntent: Parameters<ReturnType<typeof installed.economy.iap>['complete']>[1],
+) => Effect.gen(function* () {
+  const service = installed.economy.iap()
+  const accepted = yield* service.redeem(subject, originalIntent)
+  const observedCompletion = yield* service.complete(subject, originalIntent)
+  return { accepted, observedCompletion }
+})
+```
+
+The account, prepared purchase-admission source, item participant, catalog and OAuth
+source are actual application inputs, not supplied credentials or permissive policy
+defaults. The example targets sandbox declarations; a real test purchase/credential
+is still required for validation. Provider completion is a remote operation after
+SQL acceptance, not one distributed transaction. If it fails or its reply is lost,
+retain the original accepted financial receipt and retry **only complete** with the
+same intention. Never mint another request or redeem another grant to finish it.
+`economy.iap.complete` is an explicit Action mounted only for configured completion
+or a complete replacement. `useCompleteIap` exposes it without automatic retries or
+a journal. It takes the original opaque mutation receipt, no player completion
+state; keep audit input redacted. A returned observation is not durable SQL proof
+of provider state and contains no raw receipt, account token or credential.
+
+All four configuration layers now report `providerCompletionInstalled` and each
+configured provider's `completionInstalled`. These report declaration bindings,
+not readiness, healthy credentials or successful purchases. A complete
+replacement owns its implementation and has no default provider list. Google
+completes by a fresh matching authenticated terminal read, including after
+uncertain POST. StoreKit transaction finishing remains an explicit native-client
+responsibility; no server-only `finish` callback substitutes for it.
+
+Synthetic finish authority proves no StoreKit purchase.
+
+`googleIapProvider({ applicationId, environment, accessTokens, timeoutMs?,
+maxResponseBytes? })` captures one installed Play declaration and creates both
+actual verification and explicit completion adapters. It supplies no OAuth
+token, price or permissive purchase policy. Provider construction does not call
+the credential source. The installed context carries captured product
+definitions; the helper removes its channel before strict Google options
+admission.
+
+
+## IAP hash-reference recovery
+
+`./iap-recovery` now supplies `createIapPurchaseRecovery`, the journal/source/
+transport interfaces and `browserIapPurchaseJournal`. One journal entry stores only
+version, stable authenticated app/tenant/account scope and the original
+channel/offer/version/request/receipt SHA256 reference. No raw receipt, OAuth token,
+provider account UUID, amount, grant or completion state is saved. Scope keys must
+contain no credentials. An actual store/secure receipt source must implement
+`restore(reference)`; a reference cannot reconstruct or authorize a purchase.
+
+```ts
+import {
+  browserIapPurchaseJournal, createIapPurchaseRecovery,
+  type IapReceiptRecoverySource, type IapPurchaseRecoveryTransport,
+} from '@voltro/plugin-economy/iap-recovery'
+import type { IapReceiptIntent } from '@voltro/plugin-economy/iap'
+
+const connectRecovery = (
+  accountScope: string,
+  actualStoreReceipts: IapReceiptRecoverySource,
+  transport: IapPurchaseRecoveryTransport,
+) => {
+  const recovery = createIapPurchaseRecovery(
+    browserIapPurchaseJournal(localStorage, navigator.locks),
+    actualStoreReceipts,
+    transport,
+  )
+  recovery.selectScope(accountScope)
+  return recovery
+}
+
+const submitSelectedPurchase = async (
+  recovery: ReturnType<typeof connectRecovery>,
+  originalIntent: IapReceiptIntent,
+) => {
+  const saved = await recovery.begin(originalIntent)
+  return recovery.retry(saved.request)
+}
+```
+
+`begin` captures the original, computes its hash and requires matching durable
+storage acknowledgement before any server mutation. `pending` only reads; it does
+not restore, purchase or finish. User-triggered `retry(saved.request)` first reads
+the original hash-only SQL observation. Accepted SQL evidence skips current
+verification and another redemption. Missing/pending reuses the exact original
+intention after the actual source restores evidence matching **every** saved field
+and hash. Never generate a new request to recover a purchase.
+
+The explicit completion callback receives the original and its actual accepted
+financial receipt. For configured Play it calls the installed complete Action; for
+StoreKit an actual native adapter must call and observe transaction.finish after SQL
+acceptance. Successful callback output must match receipt order, channel and time.
+Neither callback shape nor a synthetic finish is a provider-authenticity proof.
+Financial `fulfilled` alone, missing/pending and uncertain redemption/completion all
+keep the journal entry. Only matching completed observations clear it. No automatic
+retry, purchase, acknowledgement or finish is scheduled.
+
+The coordinator reuses the existing intention acknowledgement/lock/settlement core.
+It holds the actual supplied lock through read, restore, hash, mutation, completion
+and clearing, rechecking scope generation between asynchronous boundaries. Every
+scope selection invalidates queued work, including away and back. A scope change
+cannot cancel an already dispatched remote operation; its original journal remains
+for explicit recovery. Another reference conflicts until the original settles.
+Missing Web Locks/storage and failed acknowledgement refuse, with no memory fallback.
+
+Native implementations provide actual durable acknowledgement and matching
+process/ client locking through IapPurchaseJournal. The configuration flag
+clientRecoveryInstalled remains false because these app/engine bindings are not
+installed by the server plugin. This exported source coordinator does not
+establish any of those implementations.
+
+Browser-safe receipt admission now shares exact canonical paid units, asset IDs,
+positive transfer amounts, unique child receipts/instances and valid timestamps
+with the default SQL receipt decoder and server completion result admission. It
+decodes observations only; actual own SQL/provider authority remains required.
+No decoded object alone grants assets or completes providers.
+
+
+## Full installed IAP port and scoped fixtures
+
+The installed server layer now exposes `IapSystemPort` with all seven methods:
+initialize, account, redeem, receipt, complete, exportSubject and eraseSubject.
+`captureIapSystemService` captures real private class receivers and refuses partial
+methods/accessors. The ordinary browser-safe `IapPort` keeps its four financial/
+privacy methods; both Tags resolve the same installed owning facade. A full system
+replacement omits default accounts/SQL layers, while no configured IAP contributes
+neither IAP Tag. Readiness/privacy/lifecycle admission still belongs to the owning
+system; resolving a Tag does not independently authorize a purchase.
+
+```ts
+import { Effect } from 'effect'
+import { IapSystemPort } from '@voltro/plugin-economy/server'
+import { iapFakeLayer } from '@voltro/plugin-economy/testing'
+
+const observeFixtureAccount = Effect.scoped(Effect.gen(function* () {
+  const iap = yield* IapSystemPort
+  const subject = {
+    type: 'user' as const, kind: 'guest' as const,
+    id: 'fixture.account', tenantId: 'fixture',
+  }
+  return yield* iap.account(subject, 'ios')
+}).pipe(Effect.provide(iapFakeLayer)))
+```
+
+`./testing` exports `iapPortFixture`, fresh scoped `iapFakeLayer`,
+`iapPortSystemFixture` and `iapSystemPortSystemFixture`. These use actual
+installed SQL account/order/custody/Wallet/Inventory services with explicit
+synthetic verifier/ finish authorities and real lifecycle release. Their probes
+resolve actual Tags, replay original SQL receipts without another grant,
+complete accepted orders and observe permanent account erase fences. Scoped
+release revokes escaped facades. Fixtures supply no real provider credential,
+crypto purchase or permissive production policy.
+
+These are concrete port fixtures for Plan21, not a complete generic
+`systemContractConformance` registration. Full strategy
+defaults/events/mixins/all- table privacy/inspect/stages registration, app-owned
+replacement integration, compiled ordinary boot and every other remaining
+acceptance requirement stay open.
+
+
+## Installed Apple declaration
+
+`appleIapProvider({ applicationId, environment, appleRootCertificates, appAppleId?,
+credentials })` captures the existing actual StoreKit verifier as an installed IAP
+declaration. It uses the same application/environment/root/credential admission as
+`appleIapVerificationPort`, copies the deployment's public root bytes before lazy
+binding, and captures the actual credential-source receiver. Construction does not
+read credentials, import the SDK or contact Apple. Production requires the numeric
+Apple app ID as well as the application bundle ID. Missing real credentials fail
+activation; no generated third-party credential or unsigned purchase mode exists.
+
+```ts
+import { economyPlugin } from '@voltro/plugin-economy'
+import {
+  appleIapProvider,
+  type IapPluginOptions, type AppleIapCredentialSource,
+} from '@voltro/plugin-economy/server'
+
+const installAppleEconomy = (
+  currencies: Parameters<typeof economyPlugin>[0]['currencies'],
+  iap: Omit<IapPluginOptions, 'providers' | 'service' | 'querySources'>,
+  applicationId: string,
+  trustedDeploymentRoots: readonly Uint8Array[],
+  credentials: AppleIapCredentialSource,
+) => economyPlugin({
+  currencies, realMoney: true, iap: {
+    ...iap, providers: [appleIapProvider({
+      environment: 'sandbox', applicationId,
+      appleRootCertificates: trustedDeploymentRoots, credentials,
+    })],
+  },
+})
+```
+
+The factory removes the installed channel before the strict Apple options decoder
+and supplies actual captured product definitions. It does not add a server completion
+factory. StoreKit transaction.finish belongs to an actual native client **after** the
+matching SQL grant has been accepted; its recovery source/finisher can use the
+explicit hash-reference coordinator above. The inspect channel correctly reports
+completionInstalled:false for this declaration; this is not an unfinished HTTP
+fallback to a server-only finish callback.
+
+Their public root construction seam is not an Apple trust chain; missing
+credentials refuse before SDK construction. No new table, event, credential,
+support or capacity claim is introduced.
+
+
+## Authenticated notification ports
+
+`appleIapNotificationPort` uses the existing SDK to verify Notifications-v2 and nested
+signed transactions/renewals against captured deployment roots and app/environment.
+`googleIapNotificationPort` uses the shared RS256/JWKS verifier with actual configured
+HTTPS audience, service-account email, verified-email claim and exact subscription.
+RTDN supports one-time, subscription, voided, pending-review and test hints; it does
+not declare sandbox/production. These follow the primary [Apple SDK](https://apple.github.io/app-store-server-library-node/classes/SignedDataVerifier.html),
+[push authentication](https://docs.cloud.google.com/pubsub/docs/authenticate-push-subscriptions)
+and [RTDN reference](https://developer.android.com/google/play/billing/rtdn-reference).
+
+Both server-only `IapNotificationPort` services require initialize/verify.
+Verification returns opaque process-local evidence; `iapNotificationNotice`
+reads its redacted metadata. Copies/serialized references refuse. Raw purchase
+tokens and signed data remain private. Captured byte/time budgets are not
+delivery-capacity claims. No shared webhook secret, token query-string, player
+grant/state, SQL write or automatic financial adjustment is added.
+
+Notification authentication **does not establish current financial state**.
+Fresh provider lookup, accepted SQL owner/custody, deduplication, ordering,
+durable receipts, renewals/refunds/debt and paid-asset disposition remain
+required construction work. The verifier alone installs no route; the explicit
+optional installed notification/refund binding is described below. Do not
+acknowledge provider delivery as durably processed using this verifier alone.
+
+`./testing` exports fresh scoped `iapNotificationPortFixture`,
+`iapNotificationFakeLayer` and `iapNotificationPortSystemFixture`. Their
+explicit synthetic TEST authority has no purchase identity or grant/refund
+authority; normal scope release permanently revokes verify/initialize. Shared
+verifier and SDK mocks only measure seam configuration and refusal, not real
+cryptographic or delivery behavior.
+
+## Accepted SQL notification targets
+
+`IapSqlService.prepareNotification(deployment, authenticatedNotice)` is a trusted
+server-only read helper. Capture the realMoney/channel/app/environment declaration
+from server configuration; never take it from the player or the push body. The
+notice must be the original process-local evidence returned by an authenticated
+notification adapter. The helper looks up the globally claimed transaction identity,
+checks its actual namespace, owner privacy and accepted SQL custody, and decodes the
+original immutable order snapshot and financial receipt. It performs no seeding,
+clock read, current verifier/admission callback, asset write or provider call.
+
+```ts
+import { observeAcceptedIapNotificationTarget } from '@voltro/plugin-economy/server'
+
+const target = yield* orders.prepareNotification(deployment, authenticatedNotice)
+const original = yield* observeAcceptedIapNotificationTarget(target)
+```
+
+The opaque target exposes only orderId/noticeId. `observeAcceptedIapNotificationTarget`
+repeats the actual SQL/privacy reads before returning the original receipt and the
+redacted authenticated notice. Spread/JSON copies have no authority. Erasure,
+missing/corrupt custody, foreign namespace/app/SKU/original transaction and changed
+order ownership refuse; a saved target cannot bind another order. A nullable RTDN
+environment is resolved only through the captured declaration and a matching actual
+accepted SQL identity. That establishes SQL scope, never current Google state.
+TEST notices and review hints without a transaction identity cannot select a purchase.
+
+This read-only capability authorizes neither a grant nor a refund. Current
+provider status must be looked up separately before a financial adjustment;
+provider I/O and SQL erasure are not one atomic transaction. No raw push
+material or owner identity is projected through this observation helper. No new
+tables or installed webhook route are added by this read helper alone; optional
+installed binding is described below.
+
+## Fresh IAP provider status
+
+`IapCurrentStatePort`/`iapCurrentStatePort` is a server-only initialize/read seam.
+It requires the original opaque accepted SQL notification target and captured
+realMoney/app/channel/environment/account configuration. `IapAccountsPort` now
+also supplies `observe`: it reads and validates an existing SQL binding without
+minting, seeding or fence updates. Missing, corrupt or erased bindings refuse.
+This observation path, rather than the allocating `read`, gates the new status
+service. Original SQL and current account are rechecked after external I/O and on
+every subsequent use of the opaque status evidence.
+
+```ts
+import { iapCurrentPurchaseState } from '@voltro/plugin-economy/server'
+
+const accepted = yield* orders.prepareNotification(deployment, authenticatedNotice)
+const verified = yield* currentProvider.read(accepted)
+const status = yield* iapCurrentPurchaseState(verified)
+```
+
+`googleIapCurrentStatePort` uses the same bounded, authenticated, fixed Products v2
+GET as the verifier/completion adapters. It reads the purchase token only from the
+private authenticated notice, checks its hash against accepted SQL, and compares
+actual account, app/environment, SKU, purchase time and quantity. Current
+refundableQuantity gives an exact cumulative share `(quantity - refundableQuantity)
+/ quantity`; provider consumption/acknowledgement can advance. A missing/error,
+pending or inconsistent cancelled response never implies a full refund.
+
+`appleIapCurrentStatePort` reads current operator credentials, calls the real SDK
+getTransactionInfo and verifies that response with captured public Apple roots,
+online checks and app/environment scope. Purchase identity/value/account admission
+is shared with the original verifier. Legacy date-only/full refund gives 1/1;
+REFUND_PRORATED uses exact integer milli-percentage / 100000. Contradictory fields,
+unsupported Family Sharing revoke and foreign/changed purchase facts refuse.
+
+Opaque evidence exposes only orderId. `iapCurrentPurchaseState` returns redacted
+state, exact refundNumerator/refundDenominator, observedAt and optional revokedAt.
+Copying this projection does not restore evidence. maxAgeMs (default 30000) is an
+evidence lifetime budget; expiry or clock rewind refuses. It is not a provider
+consistency or latency guarantee. SQL/account erasure and provider I/O remain
+separate transactions; a future financial writer still needs its own SQL fence.
+No refund, debt, entitlement, provider mutation, new table or installed webhook
+route comes from this read service. notificationInstalled/refundDebtInstalled stay
+false; no raw token, signing key or owner identity reaches its public projection.
+
+Twelve source scenarios cover existing-account observation, actual SQL/account
+revalidation, provider callsites/projection/transport refusal and scoped Tag
+release; one native independent-pool scenario per six variants is authored.
+Provider HTTP/SDK/authenticated-notice seams are explicit; no real purchase,
+push, signature/OCSP or sandbox delivery proof. `./testing` exports fresh
+iapCurrentStatePortFixture/iapCurrentStateFakeLayer/iapCurrentStatePortSystemFixture
+with actual accepted SQL and an explicit active-provider seam.
+
+Provider field contracts: [Google Products v2](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2),
+[Apple transaction payload](https://apple.github.io/app-store-server-library-node/interfaces/JWSTransactionDecodedPayload.html)
+and [Apple revocation types](https://apple.github.io/app-store-server-library-node/enums/RevocationType.html).
+
+## Durable encrypted IAP notice custody
+
+The explicit server-only `./iap-notifications` entry adds
+`IapNotificationCustodyPort`/`dataStoreIapNotificationCustody`. Its three table roles
+are notice namespace/count admission, subject privacy/count admission and immutable
+notice identities with pending/expired/erased custody. Importing the ordinary root
+or `./server` does not import these new table declarations. This is trusted worker
+custody, not a player route or a completed refund processor.
+
+```ts
+import { dataStoreIapNotificationCustody } from '@voltro/plugin-economy/iap-notifications'
+
+const custody = dataStoreIapNotificationCustody(store, {
+  namespace,
+  deployment,
+  orders,
+  bodyRetentionMs,
+})
+yield* custody.initialize()
+const saved = yield* custody.retain(authenticatedNotice)
+const resumedNotice = yield* custody.restore(saved.id)
+const original = yield* orders.prepareNotification(deployment, resumedNotice)
+const current = yield* currentProvider.read(original)
+```
+
+Declare actual deployment app/channel/environment, a server-owned namespace and
+explicit bodyRetentionMs. Construction performs no SQL/crypto/provider I/O.
+initialize requires the registered framework FieldCipher; retain refuses missing
+cipher before notice admission/seeding and never stores cleartext. Explicit cipher
+sources may provide the same FieldCipher codec/row-binding contract; the default
+reads the registered cipher per operation so configured key rotation is observed.
+Keys and provider credentials come from the real deployment, never examples.
+
+retain first resolves the authenticated notice to actual accepted IAP SQL/privacy.
+Its immutable identity is channel/environment/app/noticeId; changed content, order
+or owner conflicts. Namespace/subject fences serialize bounded whole-namespace
+counts and privacy. The body authenticates namespace/deployment/order/owner/times/
+notice/private material/fingerprint and is sealed to its exact table/column/row
+address using the existing framework codec, as in the connection vault. sealedBody
+is deliberately plain server-only text holding ciphertext; automatic field
+middleware must not encrypt/decrypt it a second time. Unbounded SQL text follows
+the existing LONGTEXT/NVARCHAR(MAX) mapping; plaintext and sealed-body work are
+separately bounded. There is no plaintext or unbound-envelope fallback.
+
+restore requires actual retained SQL custody, row-bound authenticated decryption,
+matching metadata/body/fingerprint, current custody privacy and the original IAP
+SQL order again. It can issue a new process-local authenticated notice from that
+trusted encrypted SQL provenance after a process/pool restart. A public notice,
+serialized opaque object, copied ciphertext or changed metadata cannot do that.
+The restored notice still needs a fresh provider read before any financial action.
+Expiry is checked when the Effect runs and after original SQL revalidation.
+Restored evidence also carries an internal async SQL-custody validity check: every
+accepted-target use rechecks this exact encrypted row, privacy and expiry before
+entering the IAP transaction. Holding a restored notice does not bypass pruning
+or erasure. The two transactions remain separate, without a nested SQL lease.
+
+pending returns bounded redacted receipt identities; it is not a processed-status
+or refund guarantee. Explicit prune removes expired private bodies, keeps identity
+and refuses payload recreation on redelivery. No automatic retention schedule is
+installed yet. Export returns owned metadata without raw tokens/ciphertext; erase
+removes owner/body and permanently fences recreation. Erase also works without a
+cipher or with corrupt ciphertext. Detected original IAP erasure during retain/
+restore triggers custody cleanup. These are separate SQL transactions; a future
+installed privacy/financial workflow must still coordinate its own fences. No
+cross-store/distributed atomicity is claimed.
+
+One native scenario per six variants covers real cipher, independent-pool
+restore, a payload beyond 65535 bytes, expiry and cipher-free erase. This is not
+executed dialect evidence. ./testing exports
+iapNotificationCustodyPortFixture/iapNotificationCustodyFakeLayer/
+iapNotificationCustodyPortSystemFixture with fresh SQL and a privately owned
+real framework cipher; it does not replace the process-global key. The
+authenticated notice is an explicit test seam. The standalone custody port
+installs no default tables or route; the optional installed notification/refund
+binding below contributes those declarations. No provider delivery, load or
+support claim follows from this source.
+
+### Current IAP state in a SQL mutation group
+
+`IapSqlService.prepareCurrentState(proof)` returns an actual-store-bound
+`PreparedSqlMutation<IapCurrentPurchaseState>` for trusted financial consumers.
+It repeats original accepted IAP custody, account binding and, for restored
+notices, encrypted notification custody/expiry inside the same SQL transaction.
+The account source must supply both `observe` and `prepareBinding`. A foreign
+store participant or serialized evidence refuses; there is no fallback.
+
+Preparation reads the opaque provider observation once. Commit uses SQL and the
+captured server clock, without a provider request or nested SQL transaction.
+The original IAP fence precedes account and notification fences. Evidence
+lifetime is checked again when the group runs. Consumers must preserve this
+lock order and finish their financial group with their own freshness check.
+The participant itself grants or reverses no assets and cannot guarantee that
+an external provider has remained unchanged since its response.
+
+Five authored memory-store scenarios cover same-store composition, post-prepare
+erasure, wallet rollback, time expiry, mixed-store refusal and encrypted-notice
+revocation/tampering. The native six-variant scenario also exercises account
+erasure from a second pool after preparation.
+
+### SQL IAP refunds, reversals and hard-currency debt
+
+The server-only `@voltro/plugin-economy/iap-refunds` entry declares four optional
+refund roles and exposes `IapRefundPort` plus `dataStoreIapRefunds`. Its five
+methods are `reconcile`, `rebuild`, `observe`, `exportSubject` and `eraseSubject`.
+It is an explicit trusted server participant; the ordinary IAP installation
+does not yet install notification routes or refund workers. Do not expose
+`reconcile` as a player-authored status/amount mutation. It accepts only the
+original opaque `VerifiedIapCurrentState` produced from accepted SQL and fresh
+provider lookup. `realMoney:false` refuses this real-money component; virtual
+wallets and virtual shop capabilities remain separate.
+
+Supply actual same-store `IapSqlService` and `EconomySqlService`, an explicit
+`debtPolicy: 'allowNegative' | 'blockSpend'`, a namespace and, for item orders,
+a same-store asset participant with a nondefault `assetsVersion`. There is one
+immutable refund cursor per accepted original across namespaces. Changing the
+namespace cannot authorize another refund of the same purchase. SQL adjustment
+history, owner fences, original IAP/account/retained-notice fences and balanced
+wallet/item movement receipts commit together. No provider I/O runs in the
+financial transaction. Whole-history/SQL-unit bounds refuse excess work.
+
+Currency reversal uses exact cumulative `floor(original * numerator /
+denominator)`. Each adjustment books only the difference from the preceding
+accepted cumulative amount. Older observed states return the newer SQL receipt;
+contradictory states at the same observation time refuse. A later fresh active
+observation compensates an earlier refund through the original source account.
+Repeated accepted observations cannot book the same adjustment again. `rebuild`
+repairs only the refund projection from complete accepted adjustment history and
+actual balanced wallet/item evidence, without replaying grants.
+
+`EconomySqlService.prepareIapRefund` uses the existing wallet writer and requires
+the opaque current-state proof and original accepted wallet receipt. Only
+hard-currency refund debits can create debt. Ordinary credits repay signed debt;
+ordinary debits cannot create or deepen it. `allowNegative` permits otherwise
+funded spending in other currencies; `blockSpend` refuses all wallet debits for
+that owner while a wallet has blocked debt. Existing blocked debt cannot be
+weakened by a later refund policy. Nullable wallet policy and owner sequence/policy
+on SQL ledger movements preserve the policy for wallet rebuild. The signed
+financial ledger remains the source of the balance, with exact BIGINT overflow
+and positive cap checks. Soft-currency debits remain nonnegative.
+
+`inventoryIapRefundAssets` reuses actual `InventorySqlService.prepareConsume` and
+`prepareGrant`. The studio must explicitly choose `disposition: 'requireAll' |
+'recoverRemaining'`. `requireAll` refuses the entire financial group when the
+requested items cannot be recovered. `recoverRemaining` removes only remaining
+owned eligible quantities and durably reports unrecoverable consumed, moved or
+locked quantities. It never pursues another owner or counts missing items as
+removed. A refund reversal restores only quantities actually recovered, with
+original attributes through current inventory admission, and tracks actual
+restored instance receipts for a later refund. The adapter does not invent an
+expired-item restitution policy or bypass changed catalog rules. A custom asset
+participant supplies prepared same-store mutations, pure receipt admission and
+SQL-only audit of its accepted movement history.
+
+Export returns owned reconciliation metadata. Erasure removes receipt bodies and
+ownership, preserves immutable identities and fences recreation; it does not
+silently cancel financial postings. The separate original IAP, account, wallet,
+inventory and notification privacy hooks must also be wired into the application
+cascade. Notification processing, installed refund/debt inspect wiring, refund
+misuse events/sanctions and store subscriptions/entitlements remain unfinished.
+
+Seven actual memory-SQL scenarios, two scoped Tag/lifetime sources and a case
+for each of six native variants have been authored, including fractional
+rounding, replay, reversal, restored-instance recovery, cross-namespace refusal,
+debt repayment/rebuild, explicit item disposition, late privacy revocation,
+expiry, bounds and cross-pool reads. They have not run; provider/notification
+projections in these fixtures are explicit seams.
+
+### Notification processor, SQL completion and explicit ingress
+
+The `./iap-notifications` server entry also exposes the seven-method
+`IapNotificationProcessorPort`: `initialize`, `ingest`, `process`, `pending`,
+`prune`, `exportSubject` and `eraseSubject`. `iapNotificationProcessor` captures
+actual notification, current-state, custody, original-order and refund ports.
+It authenticates delivery, retains the private body under the framework cipher,
+restores SQL provenance, reads fresh provider state, executes the financial
+reconciliation group and marks SQL custody `processed`. Failed provider or
+financial work leaves pending SQL for explicit retry.
+
+Custody now has eight methods, adding `markProcessed(id, receipt)`. It accepts
+only the process-local capability attached to a successful actual SQL refund
+result. A spread copy or JSON projection cannot authorize the marker. The marker
+joins fresh original/account/retained-notice and actual accepted refund-journal
+fences on the same store before changing custody. It is a second SQL commit
+after the financial group; a lost marker reply retries accepted history, without
+repeating financial value. Duplicate authenticated processed delivery avoids
+another provider call. Retention removes the processed private body while
+preserving the immutable completion marker. Owned erasure removes bodies and
+refund ownership through both ports. This is not an atomic privacy cascade over
+all application systems.
+
+`iapNotificationHttpRoute({ path, maxBodyBytes, processor })` returns a normal
+exact POST plugin HTTP declaration. Register it in `httpRoutes`; the helper does
+not start a listener. Provider signatures or push bearer authentication supply
+authority; browser cookies and query parameters do not. It applies the explicit
+byte budget, fatal UTF-8 decoding, precise method refusal, no-store responses
+and redacted authentication/retry errors. A success returns 204 only after the
+processor completes. This declared route is origin-exempt because its concrete
+notification verifier requires provider authority independent of cookies. A full
+processor replacement must preserve that authentication contract.
+
+`runIapNotificationWork({ processor, maxNotices })` prunes retained bodies and
+processes the whole bounded pending set. Excess refuses without accepting a
+prefix. Earlier successful notices survive a later firing failure and a retry
+reads SQL again. `iapNotificationSchedule({ name, cron, timezone, processor,
+maxNotices })` returns an ordinary discovered schedule descriptor. Cadence,
+registration and body retention are operator-owned; no timer or worker is
+started by construction.
+
+They include pending retry, copied-financial-capability refusal, late account
+erasure, processed-body expiry, SQL marker replay and malformed HTTP admission.
+Handler invocation is not normal gateway discovery/startup; synthetic provider
+and authentication fixtures are not genuine delivery/signature evidence.
+Optional IAP plugin binding and four-layer configuration panels are described
+below.
+
+### Optional installed notification and refund system
+
+`IapPluginOptions.notifications` now installs the actual notification/refund
+chain when explicitly configured. Its `version` must be nondefault. The SQL
+default requires operator-selected `bodyRetentionMs` and `debtPolicy`:
+`allowNegative` keeps hard-currency refund debt while permitting funded spending
+in other currencies; `blockSpend` blocks owner wallet debits until debt is repaid.
+Ordinary credits repay debt. No retention, pricing or region decision is guessed.
+Item orders additionally require an actual prepared `assets` participant and
+nondefault `assetsVersion`; `inventoryIapRefundAssets` supplies the described
+SQL recovery participant over the app's actual Inventory adapter. Currency-only
+orders may omit it. The same original/account/notice/current-state/refund/wallet/
+item SQL authorities described above govern every financial adjustment.
+
+The binding requires both `createNotifications` and `createCurrentState` on each
+configured provider. Only iOS and Android have the default chain. Apple provider
+construction shares the captured trust configuration with purchase verification
+and fresh-state lookup. Google requires explicit authenticated push configuration
+in `googleIapProvider({ ...purchaseOptions, notifications: { audience,
+serviceAccountEmail, subscription } })`; these three identities are app-owned,
+not derived from the package name. Missing factories refuse notification
+installation before credential access. Without `notifications`, purchase-only
+installations construct neither factory. Every initializer is awaited before
+IAP activation; missing required credentials or framework cipher refuse readiness.
+Declared IAP systems carry `network:outbound:*` permission for their explicitly
+supplied provider authorities, like Billing. Virtual-only installations acquire
+no IAP outbound permission or routes and refuse real-money declarations first.
+
+The normal plugin declaration adds exact POST paths `/_voltro/economy/iap/ios`
+and/or `/_voltro/economy/iap/android`. `pathPrefix` may select one safe common
+prefix; `maxBodyBytes` is the explicit ingress work budget, default 262144 bytes.
+Default `maxNoticeRows` and `maxRefundRows` are 10000-row work budgets, never
+capacity results. SQL custody is isolated per provider deployment; one shared
+refund journal keeps global original-order idempotence. No raw custody or refund
+Tag is ambiguously installed for multiple deployments.
+
+`economy.economy.iapNotifications()` and the server-only
+`IapNotificationsSystemPort` expose `initialize`, `processor(channel)`,
+`exportSubject` and `eraseSubject`. Resolve a channel-selected seven-method
+processor only after activation. Escaped processors and pending old-generation
+outcomes refuse after deactivation or rebinding. Explicit same-store rebinding
+reconstructs services from SQL without regranting assets. Initialization never
+starts its own timer, listener or worker.
+
+For ordinary file discovery, use this in an app-owned `*.cron.tsx` file. The
+cadence and budget below are examples, not an operator retention or deployment
+promise. `economy` is the actual configured plugin instance exported by that app.
+
+```ts
+import { installedIapNotificationSchedule } from '@voltro/plugin-economy/iap-notifications'
+import { economy } from '../plugins/economy'
+
+export default installedIapNotificationSchedule({
+  system: economy.economy.iapNotifications(),
+  channel: 'ios',
+  name: 'iap.notifications.ios',
+  cron: '*/5 * * * *',
+  timezone: 'UTC',
+  maxNotices: 1000,
+})
+```
+
+The descriptor captures the facade at discovery and resolves the selected
+processor at firing, so discovery needs neither activation nor credentials.
+Register one schedule per configured deployment. Pruning and pending retry use
+the existing bounded processor work; there is no automatic background runtime.
+
+A complete four-method `IapNotificationsSystemService` replacement supplies
+`service` and an explicit version, owns provider authentication/current-state/
+finance/queue/retention/privacy, and forbids default SQL/cipher/debt/assets/bounds
+options. The plugin still enforces exact HTTP paths/body budget and lifetime.
+A complete IAP replacement requires this complete notification replacement;
+default SQL notifications never borrow a replaced IAP or Wallet. Private class
+receivers are captured. Default construction adds seven notification/refund
+roles; replacement adds none. Parent initialization/export/erase include the
+selected notification system. Default erase revokes accounts first, then notice
+and refund bodies, then original IAP and root Wallet privacy. Inventory retains
+its own installed privacy hook. Partial privacy work is retryable, not atomic
+across systems.
+
+Server inspect, Shared UI, Local transport and Cloud schema/proxy now require the
+same exact `notificationSystem` shape, conditional seven roles, provider channels/
+paths, binding/version, debt/item policies and work budgets. No private token,
+notice body, owner, balance or refund outcome is exposed. Optional configuration
+sets `notificationInstalled` and `refundDebtInstalled`; absent configuration
+requires false flags and null status. Replacement shows app-owned policy/bounds.
+Both EN/DE panels retain the existing refresh/error/focus behavior. This is
+configuration, not provider readiness, authenticated delivery or financial success.
+
+`./testing` additionally exports `iapNotificationsSystemPortFixture`,
+`iapNotificationsSystemFakeLayer` and `iapNotificationsSystemPortSystemFixture`.
+Each resolves the actual installed SystemPort and processes a real SQL refund
+with a privately owned framework cipher. Provider authentication/current-state
+are explicit synthetic seams. Scope release uses normal plugin deactivation; all
+four outer methods and escaped processors become unavailable.
+
+### Accepted refund events and explicit sanctions classification
+
+Every accepted refund/reversal journal entry now commits `eventState: pending`
+and null `eventDeliveryVersion` in the same financial transaction. These two
+server-only columns belong to the existing adjustment table; no second journal
+or new table role is created. A financial rollback creates neither value nor a
+pending event. Event acknowledgement only changes delivery metadata, never
+accepted amounts, asset movements or financial bodies. Refund projection rebuild
+does not replay or recreate delivered events.
+
+`dataStoreIapRefunds` returns `IapRefundSqlService`, which includes its actual
+three-method `events` port: `pending(subject)`, `read(subject, opaqueEvent)` and
+`acknowledge(subject, opaqueEvent, deliveryVersion)`. Only system Subjects or
+verified tenant service accounts with `economy:events:write` may consume it.
+The complete bounded journal and actual accepted order/financial history are
+checked under refund namespace/subject fences. A pending object carries only its
+event ID; copies, JSON and objects from another service cannot authorize reads
+or acknowledgement. The same actual capability/version acknowledgement is
+idempotent; a changed version refuses. Delivered entries do not reopen. Refund
+erasure removes owners/bodies and delivery versions, marks event custody erased
+and revokes saved pending authority. No raw receipt/token or expired encrypted
+notification is needed to resume the already accepted financial journal.
+
+The installed default notification system now resolves this one shared queue
+through `IapRefundEventsPort` or `economy.economy.iapRefundEvents()`. It is
+lifetime- guarded. Complete notification replacements may supply their own
+`refundEvents` port; that option is forbidden for the SQL default. An absent
+replacement queue contributes no Tag and returns unavailable, never default SQL.
+The replacement owns its queue/privacy contract. All four inspect layers now
+require `eventQueue: sql | custom | null` and both panels show configured queue
+ownership and the need for an explicit delivery schedule. They display no
+pending owner/event/outcome enumeration. Optional descriptor discovery ships the
+browser- safe `./events` declarations `economy.refunded` and
+`economy.refundReversed` only when an event queue is configured; the production
+build copies that source tree. Descriptor guards require `economy:events:read`.
+
+`deliverIapRefundEvents({ events, publisher, version, maxEvents, sanctions,
+abusePolicy })` reads the whole pending set. `maxEvents` defaults to a 1000-row
+work budget; excess refuses before any prefix delivery. `publisher.read(tenantId)`
+must supply the actual tenant-bound framework `EventPublishContext`, including
+its configured durable workflow audience. Foreign/null tenants and deferred
+transaction contexts refuse. The helper uses the existing `publishEvent`, with
+its real key/payload admission and size guard. Publication happens outside the
+financial SQL group, and acknowledgement follows successful nondeferred
+publication. A lost reply between publication and acknowledgement can duplicate
+an ephemeral event; consumers must deduplicate its stable event ID. SQL pending
+custody survives process loss. A successful acknowledgement says the framework
+publisher accepted delivery, not that a workflow finished or a client received
+it. Without a durable audience, the EventBus retains its ordinary ephemeral
+semantics. `iapRefundEventSchedule` returns a normal app-discovered descriptor;
+no timer, event bus, tenant, listener or worker is invented or started.
+
+The exported pure default `noRefundAbuseSignal` returns null. An explicit
+`abusePolicy` over actual SQL event context may return a bounded confidence
+value; it requires an actual supplied `SanctionsService.recordSignal`. The
+context reports bounded observed originals, currently refunded originals and
+refund adjustments, not all purchases or an invented refund rate. Classified
+positive refund states become trusted `rmt` signals keyed to the original order;
+replay/partial updates cannot increment a second strike for that same accepted
+original and identical classification. Changed classification conflicts.
+Reversals do not run the classifier. The Sanctions default keeps `rmt`
+review-only; automatic measures require its explicit escalation strategy.
+Missing or failing installed consumers leave SQL pending, do not repeat
+financial value and are not silently bypassed. External
+publication/classification and erasure are not one distributed atomic
+transaction.
+
+Installed Tag/lifetime sources and strict Shared/Cloud/Local/ ENDE DOM sources
+are extended. `./testing` exports `iapRefundEventsPortFixture`,
+`iapRefundEventsFakeLayer` and `iapRefundEventsPortSystemFixture`; release
+revokes actual account/journal authority plus the facade. Whole-journal cost is
+bounded by configuration but not measured. Full entitlement, sanctions workflow/
+GM/template/engine integration and remaining monetization stay open.
+
+
+### Own IAP refund disposition
+
+`IapPort.receipt(subject, originalHashReference)` and `useIapReceipt` now expose
+`partially-refunded` and `refunded` when a configured disposition reader admits
+accepted SQL refund history. Both contain the unchanged original `receipt` plus
+`refund: { sequence, state, refundNumerator, refundDenominator, observedAt }`.
+Missing and pending originals keep their existing nonterminal states. No private
+notice, provider token, fingerprint, owner or refund movement is returned.
+
+The default installed notification system supplies the actual shared refund
+adapter. The original order, retained purchase custody, refund namespace/subject,
+complete bounded adjustment history, original wallet transfers and configured
+item movement participant are read in one borrowed SQL transaction. The read
+seeds no rows, updates no admission fences, opens no nested transaction, calls no
+provider and evaluates no clock or current catalog. Invalid, erased, incomplete,
+over-budget or inconsistent history refuses rather than displaying `fulfilled`.
+The original purchase remains immutable SQL truth; this projection grants nothing
+and is not a provider observation or store-completion authority. A budget is not
+measured capacity.
+
+Standalone `dataStoreIap` accepts an explicit `refundDisposition: { read }` SQL
+reader. `dataStoreIapRefunds(...).readDisposition` implements this contract using
+the caller's transaction and admitted `IapSqlOriginalPurchase`; it cannot refund,
+repair or grant. Asset audit receives that admitted original purchase without
+requiring a retained notification body. Default installed queries conditionally
+include all four refund table dependencies for LiveQuery invalidation; absent
+notification configuration adds none.
+
+A complete notification replacement over default SQL IAP may supply its own
+`refundDisposition` reader and must declare actual nonempty IAP
+`querySources.receipt` dependencies. The reader preserves its receiver and must
+obey the borrowed-transaction read contract. No default refund adapter is loaned
+into that replacement. Omission reports no disposition reader and exposes only
+the original order. A complete IAP replacement owns its own `receipt` contract
+and cannot configure this default-reader seam. The four inspect layers require
+`notificationSystem.orderDisposition: sql | custom | null` and show configuration
+ownership only, never an order's refund outcome.
+
+`captureIapObservation` shares strict admission between the installed facade,
+wire schema and recovery. Financial `partially-refunded`/`refunded` observations
+retain an uncertain completion journal; they cannot replace verified store
+completion. Explicit recovery reuses the accepted original and never redeems it
+again. A failed completion keeps the original hash reference for an explicit
+retry. Client finishing may still fail for a revoked store transaction; no success
+or completion is inferred from its financial disposition.
+
+This section makes no support claim.
+
+
+### Accepted store subscription periods
+
+`dataStoreIap` can now fulfill a verified `subscription` transaction through the
+same actual account/eligibility/Wallet/Inventory/order/custody prepared group.
+Quantity is exactly one and consumption must be `none`; `expiresAt` must exceed
+`purchasedAt` and acceptance time. A later distinct verified transaction can
+fulfill its own original once. Replaying an accepted original returns its receipt
+before current verification or clock and never grants another period. Existing
+logical-offer limits continue to apply. No timer, automatic renewal or purchase
+consent is manufactured.
+
+The server-only extended SQL adapter adds `subscriptionPeriods(subject)`. It
+reads complete bounded own order/custody history and returns only
+`orderId`, `offerId`, `offerVersion`, `channel`, `startsAt`, `expiresAt` and accepted
+`refund` disposition. It does not seed, mutate, open a nested transaction, evaluate
+a clock or call a provider. A real configured refund disposition reader is
+required when an accepted subscription exists; missing admission refuses instead
+of asserting an unrefunded entitlement. Historical receipts remain readable after
+current catalog removal. Owner erasure, changed custody or corrupt history
+refuses. Structural IAP erasure no longer decodes private accepted payloads before
+redaction; valid bounded owner/custody linkage remains required and financial
+values are retained.
+
+`./iap-entitlements` is browser-safe and exports `IapEntitlementsPort`, its
+four-method service capture, `defaultIapEntitlementPolicy` and
+`resolveIapEntitlement`. `./server` exports `iapEntitlementsPort` with explicit
+`realMoney: true`, version, actual order source, optional pure policy and server
+clock. A fresh clock is evaluated after the actual SQL source resolves. Partial
+refunds remain eligible by default; a named pure policy may narrow that
+decision, including refusing partial refunds, but cannot restore a fully
+refunded, future or expired period. Duplicate order projections and nonboolean
+decisions refuse. `entitled(subject, offerId)` returns `{ offerId, entitled,
+expiresAt, observedAt }`; `expiresAt` is null when denied. The service delegates
+export/erase to the captured order owner. It creates no SQL role, listener or
+background schedule. `realMoney: false` refuses before order binding; existing
+virtual Subscription services remain usable independently.
+
+This is an observation of accepted SQL periods, not a fresh provider status or
+prepared value-write capability. No grace, billing retry, automatic renewal,
+upgrade/proration or unseen provider period is inferred. An application needs its
+actual provider renewal delivery before a later transaction appears in SQL.
+Apple's documented transaction `expiresDate` is static per transaction; a renewal
+creates another transaction with a new expiry. See [Apple expiresDate](https://developer.apple.com/documentation/appstoreserverapi/expiresdate)
+and [originalTransactionId](https://developer.apple.com/documentation/appstoreserverapi/originaltransactionid).
+
+Deliberately supplied completion authorities may now accept a subscription's
+actual original SQL capability. That does not install a native finish callback:
+StoreKit finish remains client-owned, and the current Google Products-v2 adapter
+still refuses subscriptions. Installed default admission and entitlement routes
+are described below; the configured flag is conditional.
+
+Provider projection/completion fixtures are deliberate seams, never crypto,
+StoreKit or sandbox evidence. No support or capacity claim.
+
+### Installed store subscription entitlements
+
+Optional `iap.entitlements: { version, policy? }` now binds the default accepted
+SQL-period port. A subscription product in the default installed IAP system
+requires this configuration. Default entitlements require the actual installed
+refund disposition reader; an absent reader refuses construction. Explicit
+nondefault rule identity is required. The named pure policy may only narrow
+accepted, unexpired, non-fully-refunded periods. Configuring this port does not
+make an incompatible provider verifier accept subscriptions. The Google adapter
+now selects its separate Subscription-v2/Orders path described below.
+
+`economy.economy.iapEntitlements()` and `IapEntitlementsPort` resolve the same
+lifecycle-guarded four-method service. Owning activation initializes it before the
+parent becomes active; deactivation and generation changes revoke late reads.
+Default history shares the existing IAP/refund SQL roles and owning parent privacy.
+A complete `iap.entitlements.service` replacement owns expiry/history/privacy,
+requires actual nonempty `querySources`, captures class receivers, forbids a
+borrowed default policy and cascades its own export/erase. Full IAP replacement
+cannot borrow the default SQL entitlement implementation.
+
+The optional `economy.iap.entitled` query and `useIapEntitlement` accept only
+`{ offerId }` for the verified own user. Actual original/custody/financial/refund
+and explicit app dependencies invalidate the default query. A complete replacement
+uses only its declared sources. Mere passage of time is not a database change;
+`economy.iap.checkEntitlement` and `useCheckIapEntitlement` explicitly obtain a
+fresh server observation, including after `expiresAt`. The application must check
+again when it needs freshness. Privileged operations must evaluate their actual
+server authority; a cached client boolean is not permission to grant value.
+
+The four configuration layers report conditional
+`subscriptionEntitlementsInstalled` and exact `entitlementsSystem` backend/version/
+policy/SQL-history bound or app ownership. They never expose player periods,
+refund results or readiness. Failed reads hide stale configuration and retain
+reload focus. No configured source means no entitlement Tag, routes or RPC imports.
+Virtual/free Subscription systems remain independent under `realMoney: false`.
+
+### Google subscription originals and pinned financial status
+
+`googleIapProvider`, `googleIapVerificationPort`, `googleIapCompletionPort` and
+`googleIapCurrentStatePort` share bounded authenticated transport. Subscription
+configuration requires `subscriptionPlans`, each naming `offerId`, `offerVersion`,
+`basePlanId` and `storeOfferId` (explicit null for no store offer). Both purchase
+and financial order must match that mapping and the real account/app/environment.
+No missing plan, out-of-app linking, replacement, add-on or proration fallback.
+
+The verifier reads Subscription-v2 and its latest successful Orders record. Each
+paid original has the actual order ID as transaction identity; the token hash
+identifies its chain. Exact single-line paid Money is recorded at nanounit scale,
+never from reference prices. Only a processed, unrefunded, current accepted period
+can grant; server clock/consent/prepared value admission still applies. A new paid
+order can fulfill once under a new original request. Reusing the token cannot
+reuse a previously accepted order as new value. This adds no automatic renewal
+worker or native client journal.
+
+Completion revalidates the accepted SQL original and reads that pinned financial
+order even after a later renewal. Subscription acknowledgement uses the official
+endpoint, then fresh authenticated state; an uncertain POST is never a completion
+receipt by itself. Current financial reads likewise pin the original order.
+Subscription cancellation/expiry is not a monetary refund. Full refund state
+revokes; processed partial refund totals reduce to an exact bounded fraction,
+with no rounding. Unrepresentable fractions refuse. Ordinary payment, privacy,
+refund debt and item writers remain the existing SQL paths.
+
+RTDN subscription messages without an order ID now retain a chain hash and null
+transaction identity; the financial processor refuses to choose an original from
+that hint. A subscription Void RTDN carries the exact order ID and chain hash,
+then the fresh lookup authorizes any adjustment. One-time token identities remain
+unchanged. Automatic renewal routing, missed-period ingestion, account linking,
+grace/deferral/plan changes and historical provider expiry extensions remain open.
+Paid period snapshots are used conservatively with current provider admission;
+the SQL entitlement is not a claim of all current provider access.
+
+See
+[Subscription-v2](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptionsv2),
+[Orders](https://developers.google.com/android-publisher/api-ref/rest/v3/orders),
+[acknowledgement](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptions/acknowledge)
+and [RTDN](https://developer.android.com/google/play/billing/rtdn-reference).
+Generated OAuth/fetch/notice seams prove no Play purchase, cryptography, Pub/Sub
+delivery or sandbox.
+
+
+## Production license admission
+
+Declare the actual `licensingPlugin()` before this plugin in the API app. Production and staging activation require its verified active or grace deployment-wide license to grant `economy`. Explicit development/test mode stays free without recurring per-instance notices; CLI owns the actual template first-boot receipt. Tenant-scoped licenses refuse until actual tenant-bound authority exists. This server-only gate preserves normal schema, store binding and cleanup; it runs before the original activation hook, not before schema/store binding.