What Rollful does not know

Two things are deliberately missing from this API. Both are easier to understand as decisions than as omissions.

A result never says where the numbers came from

A roll tells you what the dice showed. It does not tell you how they were generated, does not carry a signature, a seed, or a proof, and it never will.

That looks like a gap until you consider what the alternative would be worth. Suppose a response carried a field saying the roll was fair. Anyone who could produce the response could produce that field, so it would prove nothing to anyone who was actually worried — while looking, to everyone else, exactly like a guarantee. A claim that cannot be checked is worse than no claim, because it invites the trust it cannot support.

So the API declines to make one. What it gives you instead is the roll itself, in enough detail to see what happened, and the honest position that you are trusting a server.

The random source stays closed

The package takes an optional random source. rollDie(sides, source) will use whatever you pass, which is how the package tests deterministic rolls.

The API does not expose that and never will. This is the one piece of the package that is deliberately unreachable over HTTP.

The reason is the same as above, turned around. A result records what the dice showed, never where the numbers came from — so a roll from a rigged source is indistinguishable from a fair one in the response. Letting a caller choose the source would mean letting them choose their results while the response still looked honest. Every roll here goes through crypto.getRandomValues and there is no parameter that changes that.

What that means for you

If you need a roll that a player cannot influence, the API gives you that: it happens on a server they do not control. That is a real property and it is worth having.

If you need a roll that a player can verify — a commit-reveal scheme, a published seed, signed results — this API does not provide it, and no dice API can provide it by itself, because the guarantee has to be built from both ends. Build that above Rollful, or somewhere else entirely.

There are no game rules here

Rollful knows what 4d6kh3 means and nothing about what you use it for. There are no character sheets, no system presets, no named rolls, no critical-hit tables, no skill checks.

This is not a roadmap item. Dice notation is shared across dozens of games; the rules are not. The moment an API takes a position on what a natural 20 means, it belongs to one game and is in the way of every other. naturalHigh is reported as a fact — this group kept one die and it showed its top face — and what that means is yours to decide.

The practical version: everything system-specific belongs in your code, above this API, where it can differ per game without asking anyone’s permission. Rollful stays the layer that just rolls dice.

Where to go next

• Why every die comes back — what the API does report, and why.
• Versioning — both of these restated as commitments.