TokenAccount
object type
A TokenAccount — **the ONE-per-GROUP token wallet / platform billing unit** (AT/stack billing of MERCHANTS; 1 org or 100 orgs share ONE pool — is the billing aggregation point; per-org figures are consumption ATTRIBUTION, reporting-only). The wallet is a GROUP-scoped SINGLETON enforced by the tokenAccountSingleton UNIQ marker minted IN the create txn. **Wallet existence IS the metering arm** (ruling): no wallet ⇒ the group is unbilled (the DVLP posture); opening one arms the rater (the slice-4 leg). balance = Σ TokenEntry amounts EXACTLY, cached in the SAME transaction as every ledger append — SIGNED (ruling: the ledger never lies; a transient sub-zero overshoot is honest state; exhaustion balance ≤ 0 fires the system:token_exhaustion CASCADE-suspend of member orgs, reload ≤0→>0 fires system:token_reload unsuspend-to-ACTIVE). The auto-top-off block is CONFIG this slice (the FIRING engine + stored-method custody = the rater leg, deferral 5); its budget cap is a LAZY month-keyed counter (ruling — rolls by key comparison, no scheduled reset). FSM: active(i) ⇄ inactive (paused — purchases/grants refuse REF_STATE; the rater still debits: usage happened) → doomed (gate-protected; the inbound-ref set is EMPTY by design — entries and purchases are FAMILY [the GiftRegistry vacuous-gate class]). Platform billing is USD-only. NOT searchable (platform-internal — never merchant search content). Template class A16_BILLING (platform billing ≠ floor work — owner/manager/assoc_mgr; hand-derived v23).
Fields
| Field | Type | Notes |
|---|---|---|
id | ID ID! | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
sysId | String String! | The group-scoped human-facing system id (TA-…). |
type | String String! | The kind of record — always TokenAccount here. |
caption | String String! | The record’s display name — what people see it called. |
status | String String! | The FSM state: active | inactive | doomed. |
parentId | ID ID! | The parent org group; for a TokenAccount parentId === rootId. |
rootId | ID ID! | The org-group family root. |
createdAt | String String! | When the record was created, as a UTC timestamp. |
updatedAt | String String! | When the record last changed, as a UTC timestamp. |
revisionNum | Int Int! | How many times this record has been edited; the first save is 0. |
revision | ID ID! | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
refCaptions | RefCaption [RefCaption!]! | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
balance | Int Int! | The cached token balance = Σ TokenEntry amounts EXACTLY — SIGNED. NEVER caller-writable — moves ONLY with ledger appends. |
lowBalanceThreshold | Int | The low-balance warning threshold (tokens) — absent ⇒ the warning arm is unarmed (the eventDate optional-arm class). The warning ladder is EVENTS + readable state now. |
dailyBurnThresholdKernels | Int | The daily-burn alert threshold in KERNELS/day. Absent ⇒ unarmed. Owner-set like lowBalanceThreshold; day rows over it read as breaches on the costs face (the engine-evented twin is a named wordable beside delivery). |
autoTopOff | AutoTopOffConfig | The auto-top-off block — absent ⇒ never fires. CONFIG this slice; the FIRING engine + stored-method custody ride the rater leg. Cap reached ⇒ STOP + WARN (never charges past the budget — the operator law). |
autoTopOffMonth | String | The auto-top-off cap window's YYYY-MM month key — SERVER-stamped at fire time. |
autoTopOffSpentUsdCents | Int | The month's cumulative auto-top-off spend — SERVER-stamped at fire; compared against the cap BEFORE each fire. |
autoTopOffDay | String | The auto-top-off DAY window's YYYY-MM-DD key. |
autoTopOffSpentDayUsdCents | Int | The DAY's cumulative auto-top-off spend. |
autoTopOffPendingMethod | String | WHICH stored card the in-flight top-off charged — primary | backup. |
autoTopOffPrimaryFailedDay | String | The UTC day the PRIMARY card last webhook-failed a top-off. |
autoTopOffBackupFailedDay | String | The backup twin — both stamps reading TODAY = the cards-failing emergency (nothing fires; the loud lane speaks each tick). |
backupBillingMethod | BillingMethodFacts | The BACKUP method's readable facts. The charger's top-off falls back to it when the primary declines; stamped by attachTokenAccountBackupBillingMethod, removed whole by its detach. |
burn7dKernels | Int | COMPUTED at read: the group's total kernel consumption over the LAST 7 UTC days, summed off the rater's TOTAL day lanes (the usageReport engine — exact integers). 0 on a quiet week; null only on the filtered listing lane (vitals ride the plain reads). |
runwayDays | Float | COMPUTED at read: the balance SCALED TO KERNELS (balance is whole internal tokens — ×1,000,000) ÷ the 7-day daily kernel burn — how many days the balance lasts at the current rate. Null when the burn is 0 (no rate exists to project) or on the filtered listing lane. |
microTokenCarry | Int | The sub-token usage accrual in µtokens, 0…999,999. SERVER-stamped — no face carries it; absent = 0. Read-exposed for transparency. |
lowBalanceSince | String | When the CURRENT low-balance episode began. The readable half of the warning ladder — the at.billing.token_account.low_balance.v1 event is its evented twin. |
billingMethod | BillingMethodFacts | The stored off-session method's READABLE facts. Present ⟺ custody is armed (the charger's top-off + base-fee arms both require it); stamped by attachTokenAccountBillingMethod, removed whole by detach. |
autoTopOffPendingPurchaseId | ID | The in-flight auto-top-off TokenPurchase. Absent = no fire in flight. |
topOffCappedSince | String | When the CURRENT capped episode began. Absent/null = not capped. |
baseFeePaidMonth | String | The latest UTC YYYY-MM period the base fee SETTLED for. Absent = never collected. |
includedMonth | String | The live included-allowance month, UTC YYYY-MM. SERVER-stamped by the base-fee settle; absent/null = no allowance ever minted, or the plain-read vitals lane was skipped (the burn7dKernels listing-lane class). |
includedGranted | Int | What the live allowance month MINTED (tokens — monthlyIncludedTokensFor at the collected amount). Present ⟺ includedMonth is. |
includedRemaining | Int | What the live allowance month has NOT yet drawn (tokens; drains floor-0 as the month meters; 0 after the month-roll expiry sweep). The banked balance = balance − this figure while the month lives. Present ⟺ includedMonth is. |
affiliateCreditCents | Int | Your group’s SPENDABLE referral-earnings credit (USD cents ≥ 0): Σ your AffiliateAccrual entries exactly. When it covers your monthly base fee the cycle CREDIT-SETTLES automatically (no card charge — bill-netting first, the ruled settlement order). Absent/null = never earned a cent, or the filtered listing lane (the burn7dKernels class). |
frozenKernels | Int | Σ kernels in transfer-FROZEN blocks: your TRUE spendable room = balance − this figure (the exhaustion gate reads it; the transfer face’s pre-submit warning derives from it). Absent/null = nothing frozen, or the filtered listing lane. |
storageSnapshotDay | String | The latest UTC YYYY-MM-DD day a storage snapshot EMITTED for this wallet. Absent = never snapshotted. |
currency | String String! | Platform billing currency — 'USD' by law. |