revshare package

 1components            : subscriptions (live realm — the revenue
 2                        machine and the upstream custodian),
 3                        feeledger (member balance accounting,
 4                        fee cap 0), coinio (payouts, held-balance
 5                        reads, reserve-protected sweep).
 6value boundaries      : B1 subscriber EOA -> subscriptions (plan
 7                        price, origin envelope; governed by
 8                        subscriptions' own H == U + F). B2
 9                        subscriptions -> revshare (banker send:
10                        ClaimAll pays the caller, and the caller
11                        is this realm). B3 revshare -> member EOA
12                        (coinio.Payout on Claim/ClaimAll).
13who owns which state  : subscriptions owns plans, subs and the
14                        provider's claimable balance (revshare's
15                        RECEIVABLE); revshare owns the member
16                        table, weights, and the member balances in
17                        its own ledger. No state is shared; the
18                        only coupling is the crossing calls and
19                        the coins that move over B2.
20who controls funds    : upstream, only a claim by this realm can
21                        move its receivable (provider-keyed
22                        ledger). Here, member balances move only
23                        to their owner (pull claims); the admin
24                        can NEVER touch earned balances — sweep
25                        reserves them, weight changes affect only
26                        FUTURE distributions.
27identity propagation  : downstream sees cur.Previous() = THIS
28                        realm on every crossing call, so the plan
29                        provider and the claim beneficiary are the
30                        realm address by construction — no admin
31                        or member identity ever reaches the
32                        downstream realm.
33conservation          : Held == UsersTotal + S (surplus above the
34                        Liabilities() reserve, recoverable only by
35                        SweepDenom). Distribution is exact: shares
36                        are floor(amount*w/W) via the
37                        overflow-free split (A/W)*w + ((A%W)*w)/W,
38                        and the remainder goes to the
39                        highest-weight member (ties: lowest
40                        address) — fee_split's deterministic dust
41                        policy, so no residual pool exists.
42                        Cross-boundary: lifetime Pulled equals the
43                        sum of all distributions, and the
44                        downstream receivable is NOT part of Held.
45ordering              : Pull refuses BEFORE the downstream call
46                        (no members configured = refuse), claims
47                        downstream, MEASURES the arrival as a
48                        held-balance delta, then distributes
49                        exactly what arrived. State-after-call:
50                        the only local mutations happen after the
51                        boundary, on measured coins.
52downstream abort      : "nothing to claim" (or any downstream
53                        panic) aborts the whole Pull — no local
54                        state exists yet to corrupt, by ordering
55                        AND by VM atomicity. There is no recover
56                        anywhere in this realm, and none may be
57                        added.
58replay                : a second Pull finds a zero downstream
59                        balance and aborts there. Distribution
60                        credits are driven by the measured delta,
61                        so a replayed Pull cannot double-count
62                        even in principle.
63trust                 : revshare does not trust the downstream
64                        reply beyond "it did not abort" — it
65                        distributes the measured balance delta,
66                        not a reported amount. Downstream
67                        validates nothing about this caller; the
68                        provider ledger is keyed by address.
69terminal states       : plans retire downstream (provider-only,
70                        exposed here admin-gated); members can be
71                        removed (earned balances survive removal
72                        and stay claimable); the realm itself has
73                        no terminal state — a team that walks away
74                        leaves only pull-claimable balances.
75adversarial callers   : Pull is permissionless — it can only move
76                        the receivable into member balances at the
77                        fixed weights, so a stranger's Pull is a
78                        free favor. Plan creation/retirement is
79                        admin-gated (the downstream per-provider
80                        plan quota is a griefable resource).
81                        Members trust the admin for FUTURE weights
82                        only, never for earned balances. All
83                        entrypoints refuse coin-carrying
84                        transactions (the downstream assertNoSend
85                        reads the origin envelope; ours matches).