inventory: tokens() skips any token with no assets, so a coinless token is invisible

[MastaP]

Problem

tokens(registry, filter) drops every mirror entry whose first asset is absent, so a coinless
token — one whose genesis data carries no value envelope — never appears in the wallet's token list.

dist/index.js of 0.16.0, :12985-12991:

tokens(registry, filter) {
  const out = [];
  for (const [tokenId, entry] of this.mirror) {
    if (entry.status !== "active") continue;
    const asset = entry.assets[0];
    if (!asset) continue;                    // <- a coinless token exits here
    if (filter?.coinId !== void 0 && asset.coinId !== filter.coinId) continue;
    …

The guard is not itself wrong — toToken(tokenId, entry, asset, registry, …) takes asset as a
required argument, so skipping was the only safe thing to do when every indexed token was guaranteed to
have one. That guarantee no longer holds.

Why it changed

wallet-api ships coinless tokens as of unicity-sphere/wallet-api#140 (cb4c275, deployed). Such a
token is indexed as an ordinary active row with zero asset rows, and GET /v1/inventory returns it
with assets omitted and a new tokenType field. Verified end to end on staging: mint, deposit,
owner-to-owner transfer, claim, spend and restore all work.

The sync path already handles the new shape safely — applyOne (:13070-13082) normalises with
assets: item.assets ?? prev?.assets ?? [], so the mirror entry is always an array and nothing throws.
Confirmed by driving the shipped 0.16.0 client against deployed staging holding a coinless token: it
authenticates, syncs, parses the response including the unknown tokenType field (parseJsonBody is a
bare JSON.parse, no strict rejection), and reports correct balances. The token is simply absent
from tokens().

So this is a display gap rather than a correctness bug: the token is held, tracked in the mirror,
spendable and transferable through the lower-level paths. It just cannot be seen.

Fix

Make the asset optional through tokens() and toToken rather than filtering the entry out. Two
questions that belong to whoever owns the token model:

1. filter.coinId. A coinless token matches no coin id. It should presumably be excluded when a
   coin filter is supplied and included when none is, which falls out naturally if the filter check
   moves inside an asset !== undefined branch.
2. What the token carries instead of coinId/amount. wallet-api now indexes and returns
   tokenType — the 1–64 byte genesis type — precisely so a client can name the KIND of token it
   holds. Note it is a class label, not an identity: token_id is the instance key, and every
   token of one kind shares a type. Canonical per-network ids live in the upstream registry
   (unicity-ids.<network>.json, the assetKind: "non-fungible" entry — testnet2 971a26ee…,
   mainnet 9f190eea…), but a minter may use its own and the token is still valid, so a recognition
   table must be keyed by network and must not reject an unrecognised type.

Caveat for grouping: SphereTokenEngine.mint() derives tokenType per operation and split outputs
derive it per output ordinal, so for ordinary value tokens it is per-mint noise, not a class. Only
a caller-supplied type (as mintDataToken takes) is a stable class identifier.

Acceptance

• A coinless token appears in tokens() when no coin filter is supplied.
• A coin-filtered call still returns only tokens carrying that coin.
• Valued tokens are unchanged.
• Nothing throws for an entry with an empty asset list.

Related, not duplicate

• feat(payments-v2): represent and expose non-fungible tokens — tokens() drops every coinless token #777 — client representation of coinless tokens (this is one concrete
  symptom of it; filing separately because the guard above is a specific, self-contained fix).
• history: a coinless receipt posts [{coinId:"", amount:"0"}] and is silently dropped #780 — a coinless history receipt is posted as [{coinId:"",amount:"0"}]
  and silently dropped. Different path, same root cause: the client assumes a token has ≥ 1 asset.
• isSpherePaymentData silently reads a valid value envelope as a valueless data token #778 — isSpherePaymentData misreads a valid envelope as valueless.

[MastaP]

Implemented, but not by the fix this issue proposes — flagging the difference so it is a
recorded decision rather than something to discover in the diff.

What this issue asked for

Make the asset optional through tokens() and toToken rather than filtering the entry out.

What was built instead

A separate, disjoint read:

payments.coinless(): CoinlessToken[]
payments.tokenData(tokenId): Promise<Uint8Array | null>

tokens() is unchanged, including the if (!asset) continue guard this issue points at. A
coinless token never enters it.

Why

Token (types/index.ts) declares coinId, symbol, name, decimals and amount as required
readonly fields. Making the asset optional means one of two things, and both are worse than a
second read:

• Optional fields — coinId?, amount? — is a source break for every consumer that reads
  them today, and there is no seam to soften it: the Connect wire IS types/index.ts Token by
  structural pass-through (sphere_getTokens → stripTokenSdkData, unknown[] in and out), with
  no independent declaration and no per-request version to gate on.
• Sentinels — coinId: '', amount: '0' — keeps the type intact but puts untrue values in
  money-shaped fields. Anything that sums amount or formats by decimals silently folds an NFT
  into a balance. This is the same shape as the bug in history: a coinless receipt posts [{coinId:"", amount:"0"}] and is silently dropped #780, where a synthetic coinId: '' was
  posted to history and refused; wallet-api's reasoning there applies here too — a second spelling
  of "no coin" is a thing every consumer then handles forever.

A coinless token's identity is (tokenId, stateHash). It has no amount, no decimals and no symbol,
so it is not a Token, and the disjointness is enforceable: an active mirror entry is coinless
exactly when it is not a coin token, so it appears in exactly one read. MirrorEntry.coinless is
computed once at apply time and pinned by tests both ways.

The cost, stated plainly: a consumer that wants one list has to call two methods and concatenate,
and dApps see NFTs only after their wallet host surfaces the new read. The gain is that every
existing tokens() / assets() consumer is byte-identical.

The two open questions, answered

1. filter.coinId. Dissolves. A coinless token is not in tokens() at all, so
tokens({ coinId }) is unchanged — no branch, nothing to exclude.

2. What it carries instead of coinId/amount. tokenType, exactly as suggested, plus
stateHash, transferring, suspectedSpent and timestamps. Two points from wallet-api#147 are
built in: the recognition table is TokenRegistry.getTypeDefinition(), keyed on the token-type
namespace rather than the coin one — one registry file holds both, discriminated by assetKind,
and the flat definitionsById map cannot tell a type from a coin id — and an unrecognised type is
never rejected or hidden, since a minter may use its own. tokenType is treated as a class
label throughout, never an identity: tokenId is the instance key.

The payload is tokenData(tokenId), not a field on the row. Genesis data is the NFT's actual
content and is unbounded, and blobs are lazy under server custody, so a list read must never carry
it.

Also fixed on the way

transfer:incoming announced a coinless arrival as tokens: [] — the event fired with nothing in
it, so a UI listening for arrivals saw nothing land. It now names the token in a disjoint
coinless field.

One real bug surfaced by a mutation probe: recoverOne flips status in place without recomputing
coinless, so without the status guard in isCoinless a recovered coin tombstone would have
appeared in tokens() and coinless() simultaneously — as an NFT, while still holding its
inherited assets.

Scope

Display and receive only. Transferring a coinless token — sendToken, the discriminated
durable intent, the Connect intent and scope — stays open under #777: it changes the money path,
where this does not.

Shipping in #779 alongside #777, #778 and #780. Not yet covered by an aggregator or staging leg:
the coinless read path is exercised against fakes, which per CLAUDE.md would pass with the CBOR
wrong, so an e2e leg against staging holding a coinless token is still owed.