The follower protocol¶
This is the contract between the harness and an engine's runner: the command line, the card check, the request and result schemas, the snapshot vocabulary, and how two snapshots are compared. It is written from the code in gorge-compliance and gorge as of 2026-11-11. Where this page and the code differ, the code is right; please tell us.
The normative sources, for when you need the last detail:
| Topic | Source |
|---|---|
The card check and the neutral object |
cmd/oraclediff/follower_export.go, file comment |
| Scenario and step types | oracle/compliance/oraclegen/gen.go |
| gorge's runner (the authoritative decoder) | gorge engine/rules/oracle_run.go |
| Decision records and snapshots | gorge engine/rules/oracle_snapshot.go |
| The comparator | oracle/compliance/oraclediff/compare.go |
| The classifier | oracle/xengine/classify/classify.go |
| A complete follower | the Forge driver, forge-oracle/ in our Forge fork |
The runner¶
A follower is one program, run in two ways:
RUNNER IN.jsonl OUT.jsonl replay every request in IN, write one result row per line to OUT
RUNNER --preflight NAMES.txt print the cards the engine lacks
The rules for a replay run:
- One row per request line, in input order. Flush after each row, so a crash keeps the rows already written.
- One bad line never stops the batch. A line you can't parse, a panic, an exception or a timeout
becomes that line's
harnessrow, and you go on to the next line. - Exit 0 when the batch ran, whatever the rows say. Exit non-zero (the Forge runner uses 2) only when the runner itself couldn't start: a missing build, a bad card database, a pin mismatch. A non-zero exit fails the whole chunk.
- Be deterministic. Seed any randomness from the request (Forge seeds from a CRC32 of the item
id). A rerun should give the same rows apart from
ms. - Each line is independent. Build a fresh game for every request. Nothing carries over between lines.
The sweep calls the runner as $XENGINE_<NAME>_RUNNER if set, else the registry's Runner. It runs
under scripts/heavy-lock.sh with --mem $XENGINE_<NAME>_MEM (default 12G). A runner that starts a
JVM also waits for one of the box's JVM slots; set JVM: true in the registry for that.
The card check (preflight)¶
oraclediff follower-export asks the runner once per run, before it writes anything:
NAMES.txt holds one card name per line, UTF-8, sorted, with no duplicates. It lists every card any
item of the run uses: each seat's battlefield, tapped, back_face, hand, graveyard, exile,
library, library_top, counters and attached cards, and the card refs in the steps (card,
targets, attackers, blocks, attached_to) with the pN: owner and #k ordinal stripped.
Tokens and player refs aren't cards and are never asked about. Names are in gorge's spelling, which is
Forge's (see card names).
The answer is one line on stdout per card the engine lacks:
NAME is exactly as NAMES.txt gave it. REASON is free text with no tab or newline, such as
not in card-data or unsupported keyword Foretell. A supported card gets no line. Blank lines are
ignored, and stderr is passed through.
Exit 0 means the answer is complete. Any other status fails the whole export, and so does a line without a tab or a NAME that wasn't asked about. A partial answer would send items the engine can't place, so it is never accepted.
Refusals. An item that uses a refused card is not sent. It is written to
<dir of -out>/<NAME>-prep.jsonl instead:
{"id":"Burst Lightning/cast-resolve/v1","reason":"toy_lacks_card","detail":"Burst Lightning: no card data"}
xengine diff reads that file and gives those items the class not_sent. The file is rewritten on
every run, even when empty.
Refuse generously. A refused card costs you a few items. A card your engine "supports" but gets wrong
in a way you already know about costs a person an afternoon reading a false diverge. If your engine
can tell that a card parsed with a gap, or falls back to a default for something it doesn't
understand, refuse it here.
Requests¶
Each line of the request file is one JSON object:
{"id": "...", "scenario_sha": "...", "item": {...}, "gorge_decisions": [...], "abilities": {...}, "neutral": {...}}
| Field | Meaning |
|---|---|
id |
The item id. Echo it in your row |
scenario_sha |
A hash of the item before any rewrite. The same item has the same sha for every follower |
item |
The scenario: setup, steps and payment. See below |
gorge_decisions |
Every choice gorge made while replaying the item. You answer your engine's prompts from these |
abilities |
For each step with an ability_index, the Forge script line of that ability. Useful if your engine reads Forge scripts; otherwise use neutral |
neutral |
Engine-neutral identities of the abilities, tokens and modes the item names. See neutral |
Kinds of item¶
All items use one schema. They differ in size and in where they start:
| Kind | id | What it is |
|---|---|---|
| Single-card scenario | <Card>/<template>/v1 |
From oraclediff gen: a small board, 0 to 4 steps. Templates: cast-resolve, play-land, activate…, combat, trigger, static, static.cost, counter-spell |
| Window | xe:<SET>:<chunk>:<game>:w<turn> |
One turn of a gorge game. The position at that turn's first main-phase priority is rebased to turn 1, with the active player relabelled p0. The steps are that turn's actions |
| Tape | xe:<SET>:<chunk>:<game>:tape |
A whole game from turn 1: each seat's opening hand and entire library, then every action until the first thing the harness can't express. Most tapes end at the first shuffle |
| Tape prefix | xe:…:tape:t<N> |
A tape cut at the end of turn N (xengine play -tape-turns) |
The item¶
| Field | Read it? | Meaning |
|---|---|---|
id, name |
Echo | Your row repeats both |
card, template |
Optional | The card under test and the generator template; empty for windows and tapes |
turn |
Yes | Absent or 1 for every generated item. A hand-written scenario may set it higher |
players |
Yes | Absent means two seats. Generated items are always 1v1 |
setup |
Yes | {"p0": Seat, "p1": Seat}, below |
steps |
Yes | The actions, below |
payment |
Yes | Parallel to steps: the exact pool mana gorge spent on step i, as WUBRGC letters (a multiset). "" means none recorded |
ignore |
No | Fields the comparator skips, such as library_top after a shuffle. You don't act on it |
compare |
No | Extra fields the comparator checks. Generated items carry none |
setup_answers, step answers, expect, observe |
No | Inputs to gorge's own runner. Use gorge_decisions instead |
xmage_* |
No | XMage driver hints |
cr, why |
No | Prose |
Setup¶
Each seat:
| Key | Type | Meaning |
|---|---|---|
battlefield |
names | Placed directly onto the battlefield. No ETB triggers, no entry replacements (enters tapped, enters with counters), no summoning sickness |
tapped |
names | Tap every battlefield placement of each name |
tapped_after_untap |
refs | Tap that one object after turn 1's untap step, at the first priority, with no trigger. Refs are seat-relative: "Forest", "Grizzly Bears#2", "token:Soldier" |
back_face |
names | Battlefield cards placed on their back face. Each also appears in battlefield |
hand |
names | Placed directly |
graveyard |
names | Placed in this order, oldest first |
exile |
names | Placed directly |
library_top |
names | The top of the library, first is top, in this exact order. Windows and tapes list the whole library here |
library |
names | Library cards in no particular order. gorge shuffles them into its deal, so an item that names library ignores library order |
counters |
{name: {KIND: n}} |
Counters added to what the card already enters with (its loyalty, say), on every placement of the name. Kinds in gorge spelling: P1P1, M1M1, LOYALTY, CHARGE, LORE, … |
tokens |
[{script, counters}] |
Tokens minted after the seat's cards, in order, silently: no create or ETB trigger. script is a Forge tokenscript stem such as r_1_1_goblin; neutral.token[stem] gives its characteristics. counters is the token's complete counter set |
attached |
[{card, to}] |
Auras placed already attached, after every seat and token is placed, with no trigger. card is seat-relative; to is a full ref |
life |
int | Starting life. Default 20 |
speed |
0–4 | CR 702.179 speed |
command, sideboard and mana exist in the type but aren't used by generated items; refuse them if
you see them.
Library filler. When a seat names fewer than 40 cards, the rest of its library is Wastes:
max(0, 40 - named) of them, placed under library_top and above any library cards. Windows and
tapes name all 40 cards, so they have no filler.
The starting point. The game starts at turn 1 with p0 active. p0 skips its turn-1 draw. The
"setup" checkpoint is taken at the first priority in p0's first main phase, even if the stack is not
empty then. Setup must leave no "this turn" history: no spells cast, no lands played, no cards entered
this turn. No mulligans and no starting-player roll happen.
Refs and object identity¶
Steps and decisions name objects by ref:
| Ref | Means |
|---|---|
pN |
Seat N, the player |
pN:Name |
The first card named Name that seat N owns |
pN:Name#k |
The k-th such card (k from 2) |
pN:token:Sub#k |
The k-th battlefield token controlled by seat N whose name contains Sub (case-insensitive) |
Create cards in gorge's order, because a ref's #k is creation order. Per seat: battlefield,
hand, graveyard, library, exile, library_top, the Wastes filler, then tokens. Each placement
binds the next ordinal of its name.
A bound ref follows its card through every zone. A ref to an object created during play (a token, a copy) means the k-th live object, in creation order, owned by seat N with that name. A name matches the card's current name or any of its face names.
Steps¶
| Op | Fields | What to do | Checkpoint |
|---|---|---|---|
play |
seat, card |
Play the land | When the land is on the battlefield |
cast |
seat, card, mana?, targets?, cast_mode? |
Add mana (WUBRGC letters) to the pool, then cast the spell, paying from the pool only |
When priority returns to the caster with the spell on the stack |
activate |
seat, card, ability_index, mana?, targets? |
As cast, for an activated ability. A mana ability completes at once |
After activation; for a mana ability, immediately |
pass |
seat |
The named seat passes priority exactly once. If another seat holds priority, that's a harness error | At the next priority, whoever holds it |
pass_to |
seat, decision? or step + active? |
Pass until the named decision (priority, attackers or blockers) is pending, or, after at least one pass, until the named step with the named active seat. decision: "priority" completes at once with no pass |
When reached |
attack |
seat, attackers, defender |
Declare those attackers, all at the one player defender ("pN") |
At the first priority after the declaration |
block |
seat, blocks |
Declare blocks, given as [blocker, attacker] pairs |
At the first priority after |
resolve |
seat |
Pass until the stack is empty and the active player holds priority. Never stop at a priority in the cleanup step | When reached |
attach |
card, attached_to |
Attach directly, with no trigger. Windows use it to place Equipment before their first step | Immediately |
move |
card, to |
Move the card directly to library, hand, battlefield, graveyard or exile, then let one empty round of priority pass so state-based actions and triggers happen |
After that round |
mana |
seat, mana |
Add the letters to the pool | Immediately |
gorge's runner also knows life, which no generated item uses.
The checkpoint after step i is named "step i (op)", for example "step 2 (cast)". You may label a
step with a different op (see rewrites): the comparator pairs checkpoints by
index.
cast_mode says how a spell is cast. "" is the ordinary way. Others name an alternative or
optional cost: kicked, kicked1, kicked2, kickedboth, multikicked, buyback, entwined,
offspring, replicated, optionalcost, plot, adventure_alt, omen_alt, modal_spell,
warped, flashback, and more as gorge supports them. If your driver can't act on a mode, list the
ones it can in the registry's CastModes. A cast with any other mode then becomes harness instead of
a false diverge.
Mana in windows and tapes. gorge's players pay their own costs, and the lowering turns every mana
ability gorge used into its own activate step with an ability_index, placed before the cast it pays
for. So your driver must activate mana abilities as standalone steps that complete immediately, and
then pay the cast from the floating pool. A producer of any colour gets a colour answer in
gorge_decisions.
payment[i] is the exact multiset of pool mana gorge spent on step i. Spend those units first.
With two or more colours in the pool, a different split is a real difference, but only if the registry
says your driver uses payment (ConsumesPayment: true). Otherwise such a difference is classed
payment_choice, not diverge.
Forge-shaped rewrites¶
Requests from follower-export carry three rewrites made for Forge, which asks for a combat
declaration before the step's first priority:
- An
attackorblockstep that declares nothing becomespass_towithdecision: "priority", a no-op checkpoint. - The
passjust before a non-empty declaration becomespass_towithdecision: "attackers"or"blockers". - gorge's own
attackersandblockersdecisions are dropped for those steps.
Step indices never move, so payment, abilities, neutral and the decisions stay aligned. An engine
that gives a priority before the declaration, as the CR does, can still follow the rewritten steps:
pass_to attackers simply passes until the declaration is due.
Decisions¶
gorge_decisions lists every choice gorge's runner made, in order. Key fields:
| Field | Meaning |
|---|---|
step |
The step it belongs to. -1 means during setup |
seat |
Who was asked |
kind |
Normalised kind: target, yesno, mode, choose_n, order, attackers, blockers |
gorge_kind |
gorge's raw kind: choose, target, arrange, modes, trigger_optional, trigger_order, … |
picks |
The labels gorge picked |
pick_refs |
The picked objects or players, as refs |
object_picks |
The picked objects, in submission order |
pick_kinds |
The kind of each pick: permanent, player, mana, color, yes, discard, trigger, sacrifice, search, x, pay_G, … |
pick_idx |
The picks' positions among gorge's options. These are gorge's option lists, not the printed card's |
resume |
Context, for example cast_modes, damage_split, look_ack |
min, max |
How many could be picked |
Priority, mulligan and starting-player choices are never recorded.
How to answer each kind of prompt your engine poses:
- Targets. Take, from this step's unused
targetdecisions in order, the refs your prompt can legally target, up to its maximum. An explicit empty answer to an "up to" prompt means no target. Divided damage is achoose_nwithresume: "damage_split", whose picks repeat a target once per point. - Yes or no.
kind: "yesno", or achoose_nwith one yes/no-shaped pick (pick kindsyes,no,opening_yes,trigger_cost_pay,decline). An empty answer declines. - Modes.
kind: "mode". The label is the mode's text. For a Charm-style spell,neutral.modealso gives the mode's position on the card. - Choosing objects (search, discard, sacrifice, choose a card). Match by ref, then by name. One gorge decision can answer several prompts in an engine that asks one card at a time.
- Trigger order.
kind: "order"with pick kindtrigger:picks[0]goes on the stack first, so it resolves last. - Scry, surveil and similar (
gorge_kind: "arrange"). The picks stay on top in pick order; the rest go to the destination the pick kind names. - X. A
choose_nwith pick kindx, or a labelX = n. - Colour, card name, number, type, copy targets. By label.
If your engine asks something gorge recorded no answer for, don't guess. Set the row's strict_miss
(see result rows). If a decision is never used, report it as leftover. Decisions
gorge made while paying (pick kinds pay_*, activate inside a payment) and look_ack never count as
leftovers.
neutral¶
gorge identifies abilities by their index in its compiled card, which follows the Forge script. An
engine that doesn't read Forge scripts needs another key. neutral provides one. Every map is always
present, and a field that can't be derived is left out, never guessed.
neutral.ability, keyed by step index, for every step with an ability_index:
| Field | Meaning |
|---|---|
class |
mana, activated, loyalty or intrinsic_mana (a basic land's CR 305.6 ability) |
ordinal |
0-based position among the card face's abilities of the same class, in script order. Absent for an ability made from a keyword line |
keyword |
For an ability made from a keyword line, the keyword and its cost, for example "Equip:1". Its position in the Oracle text isn't known, so it has no ordinal |
cost |
Normalised: mana symbols braced and run together ({2}{W}), then {T} or {Q}, loyalty as +N or -N, other parts in Forge's spelling with ~ for the card's name, joined with , |
text |
The ability's description, with ~. Absent for intrinsic_mana |
produces |
Mana abilities only: the colours one activation can add, in WUBRGC order, or any. Absent where the colour is chosen or depends on something else |
Real examples from an FDN sweep:
{"class": "intrinsic_mana", "ordinal": 0, "cost": "{T}", "produces": "W"}
{"class": "activated", "ordinal": 0, "cost": "{T}, AddCounter<1/PAGE>", "text": "Scry 1."}
{"class": "activated", "keyword": "Equip:1", "cost": "{1}", "text": "Equip 1"}
Match the class and ordinal first, then check the text. Forge script order follows the Oracle text for ordinary cards, so the ordinal is usually enough; a text mismatch tells you it isn't.
neutral.token, keyed by tokenscript stem, for every setup token:
{"r_1_1_goblin": {"name": "Goblin Token", "types": ["Creature"], "subtypes": ["Goblin"], "colours": "R", "power": 1, "toughness": 1}}
Fields: name (the script's), supertypes, types, subtypes, colours (WUBRG letters; "" is
colourless), power and toughness (numeric only), keywords, and text. Mint the token by these
characteristics. The comparator anonymises tokens, so the name you give it barely matters.
neutral.mode, keyed by the decision's index in gorge_decisions:
It covers Charm-style "choose one" spells: ordinal is the mode's 0-based position on the card. Other
choices are left out: gorge offers only the modes that are legal at that moment, so its own index isn't
the printed position.
In one FDN chunk of 574 items, every one of 3,107 ability steps got a class and cost. 3,078 got an
ordinal; the other 29 were Equip and Crew abilities, which got keyword. All 64 setup tokens and all 7
modal decisions were filled.
Result rows¶
Write one JSON object per request:
{"id": "xe:FDN:0:0:w2", "name": "...", "engine": "toy", "strict": true, "ms": 8, "snapshots": [...]}
| Field | Meaning |
|---|---|
id, name |
From the request |
engine |
Your registry name. Required when the registry says StampsEngine |
strict |
true when every prompt was answered from the script |
ms |
Wall time for the row. Not compared |
snapshots |
One at "setup", then one after each step. See below |
harness |
Set when the driver couldn't go on. Start it with harness: |
strict_miss |
The first prompt the script had no answer for, for example Missing target answer at step 3 |
leftover |
gorge decisions your engine never asked for |
| anything else | Ignored. Forge adds forge_ref, request_sha and notes, which are useful for debugging |
Stopping early. A row with harness set keeps every snapshot taken before the stop. That matters:
if gorge already differs within the stretch you did replay, the item is a real diverge, not a
harness. So take snapshots as you go and keep them when you fail.
Lacking a card at run time. If your engine finds out during a replay that it lacks a card, put
your registry's LacksCardMsg and the card's name in the harness message, for example
harness: toy lacks card: Llanowar Elves. The item is then classed as a missing card, not a harness
gap. (The class is still called xmage_lacks, from when XMage was the only follower.) Better still,
refuse the card in the preflight.
Turn caps. If your driver refuses to play past some turn, give the registry the start of that
message as TurnCapMsg. A tape that stops with it is classed turn_cap.
Snapshots¶
A snapshot is what a player can observe at one checkpoint, in gorge's vocabulary:
checkpoint "setup" | "step <i> (<op>)"
turn int
step untap upkeep draw main1 begin-combat declare-attackers declare-blockers
combat-damage end-combat main2 end cleanup
active seat
priority seat (not compared)
over bool
players[] seat, life, counters {KIND: n}?, hand[] (sorted), graveyard[] (oldest first),
exile[] (sorted; cards the seat owns), command[] (not compared), library_count,
library_top[] (top first, at most 5), pool ("WUBRGC" letters)
permanents[] name ("" when face down), controller, owner, token, tapped, face_down,
pt ("P/T", creatures only), damage, counters {KIND: n}?, types[] (card types,
supertypes and subtypes, sorted), colors ("WUBRG" letters, "" colourless),
keywords[] (sorted), attached_to (the host's current name, or "pN"),
attacking, blocking
stack[] top first: kind ("spell" | "ability"), source (the card's name), controller
Both damage steps are named combat-damage. Counter kinds use gorge's names: P1P1, M1M1,
LOYALTY, CHARGE, LORE, or another kind's name in capitals without spaces.
A real snapshot of a permanent:
{"name": "Mountain", "controller": 0, "owner": 0, "token": false, "tapped": true, "face_down": false,
"damage": 0, "types": ["Basic", "Land", "Mountain"], "colors": "", "keywords": [],
"attacking": false, "blocking": false}
gorge.jsonl in every play directory has gorge's own snapshots for each item, in exactly this shape.
gorge's also carry ref on permanents and an offered list of legal actions; you don't need either.
Card names¶
Use gorge's spellings, which are Forge's: the printed name of face 0 for a card outside the battlefield, the current face's name on the battlefield, and the first half for a split or Room card. If your card database spells a name differently (accents, punctuation, a face name), map it on the way in and back on the way out, as the XMage driver does.
How snapshots are compared¶
The comparator renders each snapshot as an ordered list of fields and reports the first difference, with its checkpoint, field name and both values. In order:
turn,step,active,over, and the number of players.- Per seat:
pN.life,pN.counters,pN.hand(as a sorted list),pN.graveyard(order matters),pN.exile(sorted),pN.library_count,pN.library_top(order matters),pN.pool(letters re-sorted to WUBRGC). permanents, as a multiset. Each permanent becomes one line of controller, owner, name, types, colours, P/T, tapped, face down, damage, counters, attachment and combat state. Tokens are anonymised totokenand matched by characteristics. Keywords are compared only when an item asks for them.stack, top first, askind:source@pN.
Not compared: priority, winner, command, permanent ref, damage outside the battlefield, and
offered unless an item asks. When both sides say the game is over, only the turn, step, active seat
and life totals are compared.
Checkpoint pairing. Your snapshot list must be as long as gorge's, and checkpoint i must have the
same label or the same step index. A different length is a harness error, unless your row stopped
early with harness set.
ignore. An item's ignore entries match fields by suffix: library_top skips both seats'.
<field>@N skips it from checkpoint N on, where 0 is "setup". Items that shuffle carry these.
What you are never sent¶
The harness only sends positions it can describe exactly, and gorge's own runner must reproduce each item before it goes out. A window is refused when its starting position holds something setup can't place, for example:
- a non-empty stack, extra turns, day and night, the monarch or the initiative;
- this-turn history: lands played, spells cast, life gained or lost, cards that entered this turn;
- a non-empty mana pool, or player counters such as poison or energy;
- face-down, phased-out, copied, mutated or melded permanents, marked damage, or combat state;
- continuous effects from a spell or ability that already resolved;
- tokens that are copies, or that lack a tokenscript.
Tapes stop at the first thing the harness can't express, most often a shuffle or another random
choice (unsupported_kind:rng). Attacks are always at one player: never at planeswalkers or battles,
and never split.
Registry fields¶
Each follower is one entry in oracle/xengine/follower/follower.go. A zero field is the behaviour of a
driver without that quirk.
| Field | Meaning |
|---|---|
Name |
The id: -engine, your rows' engine, the env prefix (XENGINE_<NAME>_…) |
Display |
The name messages print |
Runner |
The runner, relative to the repository root |
Prep |
PrepFollowerExport for a new engine |
StampsEngine |
Refuse a row whose engine isn't this one |
ConsumesPayment |
The driver spends payment[i] exactly, so a pool split after a cast is a real difference |
TurnCapMsg |
The start of the driver's turn-cap harness message (class turn_cap) |
CastModes |
The cast_mode values the driver can act on. nil means all |
SkipsDamageStep |
The engine skips the combat damage step when no creature is left in combat |
SkipsEmptyAttackStep |
The engine goes from beginning of combat to end of combat, with no declare attackers priority, when no creature can attack |
StopsInCleanup |
The engine gives priority in the cleanup step after an end-the-turn effect |
TrailingMisses |
The engine asks a cleanup discard or optional trigger after the item's last step; such a miss alone isn't decision_shape |
TapsWithCast |
The driver taps mana and casts within one priority out of turn |
TriggerOrderByName |
The driver orders triggers by text or source name, so it can't tell two from same-named objects apart |
LacksCardMsg |
The text in a harness message that names a card the engine lacks |
JVM |
The runner starts a JVM and must wait for a JVM slot |
Only set a quirk your driver has, and only once you've seen it in results. Each one tells the
classifier to stop calling a kind of difference diverge.