README
¶
gorge
[!NOTE] Documentation: adams-shaun.github.io/gorge
I want to… Start at understand how the engine works Architecture run the demo or bot-vs-bot games User's guide connect a bot (Go, Python, Java) Bots and the API reference fix a card or a rule Contributing compare speed or card coverage Performance and Card support
A deterministic, event-sourced Magic: The Gathering rules engine, written in
pure Go. Card behaviour is not hand-written per card: gorge compiles
Forge's card scripts into an
intermediate representation (IR), and the engine implements the primitives
that IR references (effects, triggers, keywords, statics, value expressions).
A card is playable when every primitive it uses is implemented; today that is
about 94% of Forge's ~34,000 scripts (make report prints the live figure).
Around the engine sit a reference server (gorged: bot tables, play-vs-bot,
HTTP + server-sent events, a Svelte browser client), baseline and hosted bot
players, and developer tools for replaying, benchmarking and auditing games.
gorge plays full games and replays them byte for byte, but it is not yet
at rules parity with mature engines and is not ready for production use.
The one design rule
Every state mutation goes through events.Apply. Nothing writes a
state.Game field except by emitting an event into the hash-chained log. So a
match is fully described by its config plus its event log: replaying a log and
resuming a match from any point in it are the same operation, and search
clones and bug reproductions reuse that one mechanism. A write that bypasses
events.Apply is a replay bug.
Quickstart
You need Go (the version in go.mod), git, make and bash.
make fetch-cards compile-cards # one-time: Forge corpus (~240 MB) into .cards/, then the IR cache
go test -run 'TestHeads$' ./engine/rules/ # a focused test; corpus tests SKIP without .cards/
make sim # 20 verified 4-seat bot games; each prints "replay OK"
go build -o bin/gorged ./cmd/gorged
bin/gorged -addr :8090 -dir /tmp/gorge-local -tables 2 -seats 4 -vsbot # then open http://localhost:8090/
The browser client is built separately with make web (needs Node); until
then the web root answers 503, but the /api/* endpoints work. Never point
two servers at one -dir.
Repository map
| Directory | What it holds | Who it is for |
|---|---|---|
engine/ |
The deterministic rules core: cards (script → IR compiler), state, decision, events, effects, rules, view, replay, deck, and seat (the Seat contract only) |
Anyone fixing a card or a rule |
server/ |
The reference server: gorged (the importable server, with an Extensions seam and RegisterNetBot), host (tables, sessions, persistence) with host/httpapi and host/manabrewhttp, protocol (the wire types), manabrew, divergence |
Server and client work |
bots/ |
Bot players: botpolicy, heuristic (the default bot), the registry, and the hosted bots (bot, lethal-pressure, sb-tactical, az-redeal) with their inference code |
Bot authors |
web/ |
The TypeScript/Svelte browser client | Front-end work |
cmd/ |
Product and developer binaries: gorged, forgec, repro, mtgsim, gentypes, pkgmap, headdiff, enginebench, cardfuzz, deckimport, … |
Everyone |
testkit/, cli/ |
Public support packages for outside modules: testkit/testutil (fixtures, corpus registry), testkit/bench (the game runner), testkit/paymirror, and cli (command-line flags, env and config) |
Contributors, downstream modules |
internal/ |
Ratchets and generators: archtest (import-graph rules), codeshape, testbudget, tsgen, corpusheap |
Contributors |
scripts/ |
Contributor and CI scripts (smoke.sh, enginebench-*, ci_shard.sh, docs_sets.py) |
Contributors, CI |
docs/ |
decisions/ (ADRs), site/ (the public docs site), agents/ (the guide for AI coding agents) |
Everyone |
Dependencies run one way, in tiers: engine/ imports nothing above it,
server/ and bots/ build on engine/, and cmd/ sits on top.
What is actually enforced is a list of forbidden import edges (for example,
effects never imports rules, view and protocol never import rules)
in internal/archtest's TestDependencyOrderHolds, not a total order. The
layout and its reasons are in ADR 0001.
four-yay, the private companion module
Draft events, training research, the research binaries (botbench,
draftsim, dzgorge, …) and the research bots live in four-yay (github.com/adams-shaun/four-yay), a
private module that imports gorge; gorge never imports it. It plugs in
through three seams: bots.Register (its bots join the registry),
server/gorged.RegisterNetBot (network-backed hosted bots) and
server/gorged.Extensions (draft events under /api/events). Its own
cmd/gorged is the full demo server. Nothing in gorge needs four-yay to
build or test.
gorge-compliance, the public compliance repository
The compliance oracles (gorge vs XMage vs Forge, card by card), the
hand-authored Oracle-text scenario audit, the XMage-ported interaction
scenarios and their coverage targets live in
gorge-compliance
(github.com/adams-shaun/gorge-compliance, public). It measures a pinned
gorge revision through gorge's exported oracle runner
(rules.RunOracleScenarioJSON, rules.RunOracleAuditScenarioJSON,
rules.CheckOracleScenarioJSON); gorge never imports it and does not gate on
it. gorge keeps the runner, its unit tests and nine residual scenario files
its own card tests load (engine/rules/testdata/oracle/), played by
engine/rules/oracle_contract_test.go as the runner's contract check.
Where to go next
- Contributing: CONTRIBUTING.md covers setup, the rules that matter, testing and the PR checklist. Fixing a card that plays wrong is walked through in docs/site/contributing/first-card-fix.md.
- Docs site: https://adams-shaun.github.io/gorge/ has the architecture, per-set card support, performance numbers and the contributor guides (sources in docs/site/).
- Design decisions: docs/decisions/.
- If you are an AI agent: start at AGENTS.md and docs/agents/.
Bot player training and adoption guidelines
Moved to docs/site/bots/training-and-adoption.md: the decision contract a bot answers, the engine's search and RL capabilities and the adoption ladder a policy climbs before it plays real users. Writing a bot in Go, Python or Java starts at docs/site/bots/ (published at https://adams-shaun.github.io/gorge/bots/).
License
gorge is licensed under Apache-2.0 (see LICENSE). Forge's card scripts are GPL-3.0, so gorge ships a
compiler for the script format and never the scripts themselves:
make fetch-cards downloads them into the gitignored .cards/ directory,
pinned to a commit (FORGE_REF in the Makefile) of the
adams-shaun/forge fork, and
engine/cards/boundary_test.go fails the build if a script is ever tracked.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bots is the registry of bot policies a host can link in.
|
Package bots is the registry of bot policies a host can link in. |
|
all
Package all links every built-in hosted bot policy.
|
Package all links every built-in hosted bot policy. |
|
azmcts
Package azmcts is the AlphaZero-style tree search of docs/design/2026-09-27-alphazero-mcts-design.md: a PUCT tree over ONE seat's searched decisions (single perspective: every value is that seat's win probability, no sign flips), whose leaf is a value -- the policynet value head, or the frozen heuristic searchprobe.LeafValue for generation 0 -- never a rollout.
|
Package azmcts is the AlphaZero-style tree search of docs/design/2026-09-27-alphazero-mcts-design.md: a PUCT tree over ONE seat's searched decisions (single perspective: every value is that seat's win probability, no sign flips), whose leaf is a value -- the policynet value head, or the frozen heuristic searchprobe.LeafValue for generation 0 -- never a rollout. |
|
azredeal
Package azredeal hosts the az-redeal policy (BP-12, spec 2026-09-28-hosted-bot-packages §11): the adapter over internal/azmcts.Seat in its honest redeal world (generation 0: uniform prior, heuristic leaf, 100 simulations, a fresh deal per simulation) that answers the searched kinds from the host's honest root and the seat's own observation feed, and plays the wrapped default bot everywhere else.
|
Package azredeal hosts the az-redeal policy (BP-12, spec 2026-09-28-hosted-bot-packages §11): the adapter over internal/azmcts.Seat in its honest redeal world (generation 0: uniform prior, heuristic leaf, 100 simulations, a fresh deal per simulation) that answers the searched kinds from the host's honest root and the seat's own observation feed, and plays the wrapped default bot everywhere else. |
|
botpolicy
Package botpolicy holds the one bot decision policy, in one copy.
|
Package botpolicy holds the one bot decision policy, in one copy. |
|
explain
Package explain is the per-intent decision note a match record carries beside its log (match-reviewer design §3, D6): who answered one decision, by which route, and -- for a search or a scoring net -- what it saw.
|
Package explain is the per-intent decision note a match record carries beside its log (match-reviewer design §3, D6): who answered one decision, by which route, and -- for a search or a scoring net -- what it saw. |
|
forgeheuristic
Package forgeheuristic registers the Forge-derived experimental policy.
|
Package forgeheuristic registers the Forge-derived experimental policy. |
|
gonet/gonettest
Package gonettest writes a tiny, deterministic network file for tests.
|
Package gonettest writes a tiny, deterministic network file for tests. |
|
netsimd
Package netsimd is a SIMD forward pass for the mlp value network (bots/gonet's network file): the same arithmetic as gonet.Net.eval, with the weights laid out transposed and padded to 64 bytes per row so every layer runs as whole-layer AVX-512 kernels (kern_amd64.s), and a scalar Go fallback (kern_generic.go) with identical semantics for every other CPU.
|
Package netsimd is a SIMD forward pass for the mlp value network (bots/gonet's network file): the same arithmetic as gonet.Net.eval, with the weights laid out transposed and padded to 64 bytes per row so every layer runs as whole-layer AVX-512 kernels (kern_amd64.s), and a scalar Go fallback (kern_generic.go) with identical semantics for every other CPU. |
|
policynet
Package policynet is the feature layer of the learned per-option policy: a deterministic, dependency-light encoder from one seat's view.View plus its decision surface into fixed-width dense scalars and hashed sparse rows, and a streaming loader for the search-teacher label corpus (four-yay cmd/searchteacher -labels).
|
Package policynet is the feature layer of the learned per-option policy: a deterministic, dependency-light encoder from one seat's view.View plus its decision surface into fixed-width dense scalars and hashed sparse rows, and a streaming loader for the search-teacher label corpus (four-yay cmd/searchteacher -labels). |
|
sanity
Package sanity is the common-sense layer of the hand-written hosted bots.
|
Package sanity is the common-sense layer of the hand-written hosted bots. |
|
sbtactical
Package sbtactical hosts the sb-tactical policy (BP-13, spec 2026-09-28-hosted-bot-packages §11): the adapter over internal/spellbench/builtins.NewTactical (the scored seat-visible heuristic behind SpellBench's sb-tactical arm) that rides the host's Env path for its planner and plays the plain View path everywhere else.
|
Package sbtactical hosts the sb-tactical policy (BP-13, spec 2026-09-28-hosted-bot-packages §11): the adapter over internal/spellbench/builtins.NewTactical (the scored seat-visible heuristic behind SpellBench's sb-tactical arm) that rides the host's Env path for its planner and plays the plain View path everywhere else. |
|
searchprobe
Package searchprobe contains the experimental history-conditioned search harness.
|
Package searchprobe contains the experimental history-conditioned search harness. |
|
searchseat
Package searchseat is the PIMC search teacher's decision function, shared by a label-corpus generator and any seat that plays the teacher's answer.
|
Package searchseat is the PIMC search teacher's decision function, shared by a label-corpus generator and any seat that plays the teacher's answer. |
|
spellbench
Package spellbench holds gorge's side of the SpellBench arena (github.com/jackmaiorino/spellbench): the benchmark deck catalogs gorge serves, and (later) the protocol adapters.
|
Package spellbench holds gorge's side of the SpellBench arena (github.com/jackmaiorino/spellbench): the benchmark deck catalogs gorge serves, and (later) the protocol adapters. |
|
spellbench/builtins
Package builtins ports SpellBench's three builtin bots -- uniform, heuristic and first (github.com/jackmaiorino/spellbench, python/spellbench/arena/bots/*.py for protocol v1 and python/spellbench/builtins/*.py on branch protocol-v2) -- onto gorge's decision model, so gorge can run a SpellBench-style workup natively (four-yay cmd/botbench -spellbench).
|
Package builtins ports SpellBench's three builtin bots -- uniform, heuristic and first (github.com/jackmaiorino/spellbench, python/spellbench/arena/bots/*.py for protocol v1 and python/spellbench/builtins/*.py on branch protocol-v2) -- onto gorge's decision model, so gorge can run a SpellBench-style workup natively (four-yay cmd/botbench -spellbench). |
|
spellbench/payexec
Package payexec lowers a gorge payment plan onto the manual mana surface.
|
Package payexec lowers a gorge payment plan onto the manual mana surface. |
|
traceboard
Package traceboard is the decision-trace board schema: the redacted, deterministic per-seat board snapshot the bot benchmark writes into every decision-trace record and the search teacher writes into every label record.
|
Package traceboard is the decision-trace board schema: the redacted, deterministic per-seat board snapshot the bot benchmark writes into every decision-trace record and the search teacher writes into every label record. |
|
Package cli is gorge's command-line layer: cobra/viper conventions built on the standard library alone (the root module has no requires; invariant 7).
|
Package cli is gorge's command-line layer: cobra/viper conventions built on the standard library alone (the root module has no requires; invariant 7). |
|
cmd
|
|
|
cardfuzz
command
Command cardfuzz plays bot-vs-bot games between randomly generated mono-colour decks drawn from the whole supported corpus, to surface engine panics, livelocks, submit errors and replay divergences that the curated repo decks never reach.
|
Command cardfuzz plays bot-vs-bot games between randomly generated mono-colour decks drawn from the whole supported corpus, to surface engine panics, livelocks, submit errors and replay divergences that the curated repo decks never reach. |
|
codeshape
command
Command codeshape prints the rules engine's code-shape metrics (internal/codeshape): functions over 300 lines in engine/rules/ and engine/effects/, Engine method count, effects.Host width, effects.Ctx and resumePoint field counts, string-literal Params reads and case literals, and the effects.Ctx / SpecContext / TriggerContext composite literals outside the context-constructor files.
|
Command codeshape prints the rules engine's code-shape metrics (internal/codeshape): functions over 300 lines in engine/rules/ and engine/effects/, Engine method count, effects.Host width, effects.Ctx and resumePoint field counts, string-literal Params reads and case literals, and the effects.Ctx / SpecContext / TriggerContext composite literals outside the context-constructor files. |
|
deckimport
command
Command deckimport turns a plain-text decklist into a repo deck file (the {name, count} JSON that testkit/testutil/decks/*.json already holds) and reports, card by card, what the corpus is missing — the gap that otherwise only surfaces at runtime, mid-deal, when the deck cannot be dealt.
|
Command deckimport turns a plain-text decklist into a repo deck file (the {name, count} JSON that testkit/testutil/decks/*.json already holds) and reports, card by card, what the corpus is missing — the gap that otherwise only surfaces at runtime, mid-deal, when the deck cannot be dealt. |
|
enginebench
command
Command enginebench re-measures gorge on the rows of draft-zero's engine comparison (docs/015-rules-engine-comparison.md §1, method in §6): random play turns/s on two FDN pairs and the Pauper Burn mirror, the heuristic bot's games/s, Engine.Clone cost on a mid-game state, one search step (Clone + Submit), and the built-in searches' per-thread rates.
|
Command enginebench re-measures gorge on the rows of draft-zero's engine comparison (docs/015-rules-engine-comparison.md §1, method in §6): random play turns/s on two FDN pairs and the Pauper Burn mirror, the heuristic bot's games/s, Engine.Clone cost on a mid-game state, one search step (Clone + Submit), and the built-in searches' per-thread rates. |
|
forgec
command
Command forgec fetches the Forge card corpus, compiles it into mtgcore's IR cache, and reports how much of it the engine can currently play.
|
Command forgec fetches the Forge card corpus, compiles it into mtgcore's IR cache, and reports how much of it the engine can currently play. |
|
gcgate
command
Command gcgate runs a package's test binary under a garbage-collector budget and fails when the collector eats more than its share of the CPU.
|
Command gcgate runs a package's test binary under a garbage-collector budget and fails when the collector eats more than its share of the CPU. |
|
gentypes
command
Command gentypes writes web/src/protocol.ts from package protocol's structs.
|
Command gentypes writes web/src/protocol.ts from package protocol's structs. |
|
gorged
command
Command gorged serves bot tables, play-vs-bot and spectating to a browser: the reference server (server/gorged).
|
Command gorged serves bot tables, play-vs-bot and spectating to a browser: the reference server (server/gorged). |
|
headdiff
command
Command headdiff shows WHAT moved a golden acceptance chain head, instead of four changed hashes.
|
Command headdiff shows WHAT moved a golden acceptance chain head, instead of four changed hashes. |
|
kcensus
command
Command kcensus is the FDN microkernel plan's Phase 0 mechanic census: it loads a deck pool, resolves every distinct card through the compiled corpus, tabulates the mechanics each card reaches (API codes along every Sub/trigger/replacement/SVar chain, trigger modes, static modes, replacement events, keyword heads, mana-cost class and non-mana cost tokens) and prints the smallest mechanic set that fully covers 50/80/95/100% of the decks, plus the share of decks that need the general layer, replacement, copy or control machinery.
|
Command kcensus is the FDN microkernel plan's Phase 0 mechanic census: it loads a deck pool, resolves every distinct card through the compiled corpus, tabulates the mechanics each card reaches (API codes along every Sub/trigger/replacement/SVar chain, trigger modes, static modes, replacement events, keyword heads, mana-cost class and non-mana cost tokens) and prints the smallest mechanic set that fully covers 50/80/95/100% of the decks, plus the share of decks that need the general layer, replacement, copy or control machinery. |
|
keywordbench
command
Command keywordbench measures keyword presence separately from event-log use.
|
Command keywordbench measures keyword presence separately from event-log use. |
|
mtgsim
command
Command mtgsim plays headless games between heuristic.Bot instances over the repo's 12 Legacy decks and verifies that each one replays to the same event chain.
|
Command mtgsim plays headless games between heuristic.Bot instances over the repo's 12 Legacy decks and verifies that each one replays to the same event chain. |
|
paymirror
command
Command paymirror plays auto-pay bot games over the repo decks and mirror- checks every planned cast: at each priority decision where a bot submits a payment-plan intent, a pre-submit clone reproduces the same cast manually (floating each planned source through the ordinary priority "activate" option, then casting and replaying the planned run's follow-up answers) and the two engines are compared for state equivalence (testkit/paymirror).
|
Command paymirror plays auto-pay bot games over the repo decks and mirror- checks every planned cast: at each priority decision where a bot submits a payment-plan intent, a pre-submit clone reproduces the same cast manually (floating each planned source through the ordinary priority "activate" option, then casting and replaying the planned run's follow-up answers) and the two engines are compared for state equivalence (testkit/paymirror). |
|
pkgmap
command
Command pkgmap generates the public docs site's package map (docs/site/architecture/packages.md includes its output): one markdown table per tier listing every Go package in the module with its one-line purpose, its non-test and test line counts, its in-repo reverse importers and its status, followed by a mermaid tier-dependency summary built from the actual imports.
|
Command pkgmap generates the public docs site's package map (docs/site/architecture/packages.md includes its output): one markdown table per tier listing every Go package in the module with its one-line purpose, its non-test and test line counts, its in-repo reverse importers and its status, followed by a mermaid tier-dependency summary built from the actual imports. |
|
repro
command
Command repro turns a feedback snapshot directory — the match.json / log.json / view.json (plus report.json) a gorged server's feedback capture (task fbrepro1) writes beside a bug report — into a working reproduction:
|
Command repro turns a feedback snapshot directory — the match.json / log.json / view.json (plus report.json) a gorged server's feedback capture (task fbrepro1) writes beside a bug report — into a working reproduction: |
|
spellbench-gorge-agent
command
Command spellbench-gorge-agent serves gorge's registered bot policies in the Spellbench v2 agent role over stdio.
|
Command spellbench-gorge-agent serves gorge's registered bot policies in the Spellbench v2 agent role over stdio. |
|
spellbench-gorge-env
command
Command spellbench-gorge-env serves the Spellbench v2 environment role over stdio.
|
Command spellbench-gorge-env serves the Spellbench v2 environment role over stdio. |
|
testbudget
command
Command testbudget enforces the per-test budget: every single test fits 4 GB RSS, 4 vCPU and 1 minute wall (operator, 2026-10-05; doubled from 2 GB / 2 vCPU on 2026-10-09).
|
Command testbudget enforces the per-test budget: every single test fits 4 GB RSS, 4 vCPU and 1 minute wall (operator, 2026-10-05; doubled from 2 GB / 2 vCPU on 2026-10-09). |
|
engine
|
|
|
cards
Package cards compiles Forge card scripts into the engine's card IR.
|
Package cards compiles Forge card scripts into the engine's card IR. |
|
cards/oracletext
Package oracletext renders the printed-card view of a corpus card -- what a player can read, never the Forge script -- for the Oracle-text card audit (docs/design/2026-09-27-oracle-text-card-audit.md).
|
Package oracletext renders the printed-card view of a corpus card -- what a player can read, never the Forge script -- for the Oracle-text card audit (docs/design/2026-09-27-oracle-text-card-audit.md). |
|
decision
Package decision defines the only vocabulary a client needs: the engine asks a Decision listing every legal Option, and the client answers with an Intent naming option indices.
|
Package decision defines the only vocabulary a client needs: the engine asks a Decision listing every legal Option, and the client answers with an Intent naming option indices. |
|
deck
Package deck reads the repo's deck-list JSON — a bare {name, count} card list — and resolves it against a cards.Registry into the flat, repeated []*cards.Card that rules.Config.Decks wants.
|
Package deck reads the repo's deck-list JSON — a bare {name, count} card list — and resolves it against a cards.Registry into the flat, repeated []*cards.Card that rules.Config.Decks wants. |
|
effects
Package effects implements the primitives Forge card scripts reference: the api: effects (DealDamage, Draw, ChangeZone, Pump, Token, ...), the filter language that matches cards and players (ValidTgts$, Defined$, Affected$), and the count: value expressions (Count$..., SVar amounts).
|
Package effects implements the primitives Forge card scripts reference: the api: effects (DealDamage, Draw, ChangeZone, Pump, Token, ...), the filter language that matches cards and players (ValidTgts$, Defined$, Affected$), and the count: value expressions (Count$..., SVar amounts). |
|
effects/params
Package params is the leaf home of the compiled ability-parameter records that both the resolution (package effects) and the payment layer (engine/rules/pay) read: the mana production record (ManaOf), the generic targeting tier (TargetsOf), the Defined-reference tier (DefinedOf, Ref) and api:DealDamage's record (DealDamageOf), plus the pure Produced$ Combo classifier (ComboColours).
|
Package params is the leaf home of the compiled ability-parameter records that both the resolution (package effects) and the payment layer (engine/rules/pay) read: the mana production record (ManaOf), the generic targeting tier (TargetsOf), the Defined-reference tier (DefinedOf, Ref) and api:DealDamage's record (DealDamageOf), plus the pure Produced$ Combo classifier (ComboColours). |
|
events
Event folds for the stack and casting: CastInfo, Resolve, Priority, Choose answers and SVar storage.
|
Event folds for the stack and casting: CastInfo, Resolve, Priority, Choose answers and SVar storage. |
|
replay
Package replay re-executes a match from its recorded event log and verifies the rebuilt event stream against the one on file, naming the first sequence number where they part ways.
|
Package replay re-executes a match from its recorded event log and verifies the rebuilt event stream against the one on file, naming the first sequence number where they part ways. |
|
rules
Package rules is the authoritative rules engine: turn structure, priority, casting and the stack, combat, triggers, replacement effects, the layer system, mana payment and state-based actions.
|
Package rules is the authoritative rules engine: turn structure, priority, casting and the stack, combat, triggers, replacement effects, the layer system, mana payment and state-based actions. |
|
rules/chars
Package chars is the read-only characteristic computation of CR 613: the layer walk that turns an object's printed face and the active continuous effects into its current characteristics (effects.Chars).
|
Package chars is the read-only characteristic computation of CR 613: the layer walk that turns an object's printed face and the active continuous effects into its current characteristics (effects.Chars). |
|
rules/combat
defender.go implements the CanAttackDefender permission static (CR 702.3b's effect half: "can attack as though it didn't have defender").
|
defender.go implements the CanAttackDefender permission static (CR 702.3b's effect half: "can attack as though it didn't have defender"). |
|
rules/cost
Package cost is the cost vocabulary every rules subsystem shares: the parsed Cost and its CostPart components, the Forge cost-string parsers (ParseCost, the strict ParseUnlessCost), the client-notation and prose renderers (FormatCost, CostPhrase) and the pure predicates and arithmetic over a Cost (CMC, WithX, Plus, Priceable, HasNonMana, the mana-symbol helpers).
|
Package cost is the cost vocabulary every rules subsystem shares: the parsed Cost and its CostPart components, the Forge cost-string parsers (ParseCost, the strict ParseUnlessCost), the client-notation and prose renderers (FormatCost, CostPhrase) and the pure predicates and arithmetic over a Cost (CMC, WithX, Plus, Priceable, HasNonMana, the mana-symbol helpers). |
|
rules/pay
Package pay is the L5 payment-planning layer of the rules engine (lasagna spec docs/design/2026-10-03-rules-engine-lasagna-design.md §9, W5 step E7, first slice): the planner's vocabulary -- a source's Alt alternatives, the Consequence an activation carries, the lexicographic Rank that orders plans, the Witness a chosen plan discloses -- and its bounded, rank-aware Search over classes of interchangeable source units.
|
Package pay is the L5 payment-planning layer of the rules engine (lasagna spec docs/design/2026-10-03-rules-engine-lasagna-design.md §9, W5 step E7, first slice): the planner's vocabulary -- a source's Alt alternatives, the Consequence an activation carries, the lexicographic Rank that orders plans, the Witness a chosen plan discloses -- and its bounded, rank-aware Search over classes of interchangeable source units. |
|
rules/resolve
Package resolve is the L6 resolution kernel of the rules engine (lasagna spec docs/design/2026-10-03-rules-engine-lasagna-design.md §7, W3; spike results 2026-10-03-s3-spike-results.md): checkpoint at the intent boundary that begins a resolution, and answer every decision posed while that resolution is in progress by re-executing it from the checkpoint with the recorded intents as an answer tape.
|
Package resolve is the L6 resolution kernel of the rules engine (lasagna spec docs/design/2026-10-03-rules-engine-lasagna-design.md §7, W3; spike results 2026-10-03-s3-spike-results.md): checkpoint at the intent boundary that begins a resolution, and answer every decision posed while that resolution is in progress by re-executing it from the checkpoint with the recorded intents as an answer tape. |
|
rules/scriptfacts
Package scriptfacts holds the pure facts a card's PRINTED text and compiled Forge script imply, derived without evaluating any game state: the printed keyword-head summary the priority walk reads off a hand card, the foretell alternative cost, a trigger's Redis 603.5 optionality, the number of turns an ability's SkipTurn rider takes, and the triggered ability a granted keyword line mints.
|
Package scriptfacts holds the pure facts a card's PRINTED text and compiled Forge script imply, derived without evaluating any game state: the printed keyword-head summary the priority walk reads off a hand card, the foretell alternative cost, a trigger's Redis 603.5 optionality, the number of turns an ability's SkipTurn rider takes, and the triggered ability a granted keyword line mints. |
|
rules/trigmatch
Package trigmatch is the trigger-mode matching layer of the rules engine: the Mode$ registry (one matcher per trigger mode, registered from each mode's file) and the per-mode predicates that decide whether one compiled cards.Trigger fires for one events.Event.
|
Package trigmatch is the trigger-mode matching layer of the rules engine: the Mode$ registry (one matcher per trigger mode, registered from each mode's file) and the per-mode predicates that decide whether one compiled cards.Trigger fires for one events.Event. |
|
seat
Package seat is who answers the engine's decisions.
|
Package seat is who answers the engine's decisions. |
|
state
ContinuousEffect and its Layer/Sublayer vocabulary live in state, below effects and rules, purely so effects primitives (Pump, PumpAll, Animate, Protection -- see mtgcore/effects/combatfx.go) can build one and hand it to rules.Engine through the effects.Host interface without effects ever importing rules (the dependency order is cards -> state -> decision -> events -> effects -> rules -> view -> seat -> replay -> cmd/*, and effects must never import rules).
|
ContinuousEffect and its Layer/Sublayer vocabulary live in state, below effects and rules, purely so effects primitives (Pump, PumpAll, Animate, Protection -- see mtgcore/effects/combatfx.go) can build one and hand it to rules.Engine through the effects.Host interface without effects ever importing rules (the dependency order is cards -> state -> decision -> events -> effects -> rules -> view -> seat -> replay -> cmd/*, and effects must never import rules). |
|
view
Package view projects one seat's view of a state.Game: a hidden zone contributes a count and nothing else unless the viewer owns it, another seat's decision is never attached, and everything that can or will hit the stack (the user's requirement R3) is described for every seat.
|
Package view projects one seat's view of a state.Game: a hidden zone contributes a count and nothing else unless the viewer owns it, another seat's decision is never attached, and everything that can or will hit the stack (the user's requirement R3) is described for every seat. |
|
internal
|
|
|
archtest
Package archtest holds no code, only tests that walk the module's import graph and fail when a dependency-order or determinism constraint from the engine spec is broken: time outside the host, effects importing rules, the wire types importing the engine, the host importing test fixtures.
|
Package archtest holds no code, only tests that walk the module's import graph and fail when a dependency-order or determinism constraint from the engine spec is broken: time outside the host, effects importing rules, the wire types importing the engine, the host importing test fixtures. |
|
codeshape
Package codeshape measures the shape of the rules engine's code: how long its functions are, how wide its interfaces and context structs are, and how much of its behaviour is still keyed on string literals.
|
Package codeshape measures the shape of the rules engine's code: how long its functions are, how wide its interfaces and context structs are, and how much of its behaviour is still keyed on string literals. |
|
testbudget
Package testbudget stores per-test-binary peak RSS records.
|
Package testbudget stores per-test-binary peak RSS records. |
|
tsgen
Package tsgen turns Go structs into TypeScript interfaces from their SOURCE, type-checked with go/types (no runtime reflection): json tags name the fields, omitempty makes them optional, pointers admit null, slices become arrays, string-keyed maps become Records.
|
Package tsgen turns Go structs into TypeScript interfaces from their SOURCE, type-checked with go/types (no runtime reflection): json tags name the fields, omitempty makes them optional, pointers admit null, slices become arrays, string-keyed maps become Records. |
|
server
|
|
|
divergence
Package divergence holds the record types and comparison predicates of the human-divergence capture (design: docs/design/2026-10-10-human-divergence-design.md).
|
Package divergence holds the record types and comparison predicates of the human-divergence capture (design: docs/design/2026-10-10-human-divergence-design.md). |
|
divergence/shadow
Package shadow computes the shadow answer B of the human-divergence capture (design 2026-10-10-human-divergence-design.md §3, §5.4): the intent a fresh, deterministically seeded instance of a hosted bot policy would give at an engine's pending decision, built from exactly the inputs the host's dispatch hands that policy.
|
Package shadow computes the shadow answer B of the human-divergence capture (design 2026-10-10-human-divergence-design.md §3, §5.4): the intent a fresh, deterministically seeded instance of a hosted bot policy would give at an engine's pending decision, built from exactly the inputs the host's dispatch hands that policy. |
|
host
Package host keeps tables running: a registry of table configurations, one goroutine per table that plays match after match with bot seats, sessions that subscribe to overview widgets or a focused table's event stream, turn-start snapshots that answer "view at seq N", append-only persistence, and crash handling that halts a table rather than hiding a bug.
|
Package host keeps tables running: a registry of table configurations, one goroutine per table that plays match after match with bot seats, sessions that subscribe to overview widgets or a focused table's event stream, turn-start snapshots that answer "view at seq N", append-only persistence, and crash handling that halts a table rather than hiding a bug. |
|
host/httpapi
Package httpapi serves a host.Registry over plain net/http: JSON GETs for tables, matches, views and events; POSTs for subscriptions; one SSE stream per client; and the embedded web client.
|
Package httpapi serves a host.Registry over plain net/http: JSON GETs for tables, matches, views and events; POSTs for subscriptions; one SSE stream per client; and the embedded web client. |
|
host/manabrewhttp
Package manabrewhttp is MB-10 of the ManaBrew protocol scoping spec (archived 2026-09-28-manabrew-protocol-scope.md (docs/design/ARCHIVE.md) §5.2): the wire transport that carries server/manabrew's translation over HTTP.
|
Package manabrewhttp is MB-10 of the ManaBrew protocol scoping spec (archived 2026-09-28-manabrew-protocol-scope.md (docs/design/ARCHIVE.md) §5.2): the wire transport that carries server/manabrew's translation over HTTP. |
|
manabrew
Package manabrew is gorge's ManaBrew translator (scoping spec role E, §5.1 and §6): a pure library that projects a seat-scoped view.View into the ManaBrew GameViewDto and maps a pending decision.Decision into the ManaBrew prompt of its decision.Kind.
|
Package manabrew is gorge's ManaBrew translator (scoping spec role E, §5.1 and §6): a pure library that projects a seat-scoped view.View into the ManaBrew GameViewDto and maps a pending decision.Decision into the ManaBrew prompt of its decision.Kind. |
|
manabrew/mbtest
Package mbtest is the ManaBrew adapter's test support (MB-8, scoping spec §5.1/§8.4/§8.5): a deterministic mock ManaBrew client that answers every prompt type server/manabrew's Translator can build, a seat.Seat wrapper (TranslatingSeat) that drives decision -> prompt -> mock response -> intent in-process, and the census/replay-equivalence tests that exercise both against real repo-deck games.
|
Package mbtest is the ManaBrew adapter's test support (MB-8, scoping spec §5.1/§8.4/§8.5): a deterministic mock ManaBrew client that answers every prompt type server/manabrew's Translator can build, a seat.Seat wrapper (TranslatingSeat) that drives decision -> prompt -> mock response -> intent in-process, and the census/replay-equivalence tests that exercise both against real repo-deck games. |
|
matchrecord
Package matchrecord is the portable record of one played game: the replay input (the match's genesis configuration and its events.Log) plus who produced it, written as one gzip-compressed JSON file per game, `<id>.match.json.gz` (match-reviewer design D1-D3).
|
Package matchrecord is the portable record of one played game: the replay input (the match's genesis configuration and its events.Log) plus who produced it, written as one gzip-compressed JSON file per game, `<id>.match.json.gz` (match-reviewer design D1-D3). |
|
protocol
Package protocol is the versioned wire between a match host and its clients: one envelope, a closed set of frame types, and JSON bodies whose TypeScript twins cmd/gentypes generates.
|
Package protocol is the versioned wire between a match host and its clients: one envelope, a closed set of frame types, and JSON bodies whose TypeScript twins cmd/gentypes generates. |
|
protocol/manabrew
Package manabrew defines the ManaBrew protocol's JSON wire types and codecs.
|
Package manabrew defines the ManaBrew protocol's JSON wire types and codecs. |
|
protocol/manabrew/internal/schemagen
command
Command schemagen writes server/protocol/manabrew/schema_gen.go: the typed JSON schema graph manabrew.Decode walks to report unknown fields, plus the target and union-member type switches, all read from the package SOURCE with go/types so the codec needs no runtime reflection.
|
Command schemagen writes server/protocol/manabrew/schema_gen.go: the typed JSON schema graph manabrew.Decode walks to report unknown fields, plus the target and union-member type switches, all read from the package SOURCE with go/types so the codec needs no runtime reflection. |
|
spellbench/agent
Package agent serves gorge's bots in the Spellbench v2 agent role, reading only the forwarded seat decision, its declared extensions and public decks.
|
Package agent serves gorge's bots in the Spellbench v2 agent role, reading only the forwarded seat decision, its declared extensions and public decks. |
|
spellbench/catalog
Package catalog holds the engine's catalog decks: the five Spellbench Pauper
|
Package catalog holds the engine's catalog decks: the five Spellbench Pauper |
|
spellbench/env
Package server implements the Spellbench v2 environment role for gorge.
|
Package server implements the Spellbench v2 environment role for gorge. |
|
spellbench/gamecfg
Package gamecfg builds a gorge engine whose every random draw comes from
|
Package gamecfg builds a gorge engine whose every random draw comes from |
|
spellbench/identity
Package identity issues Section 5.3 object ids: per viewer, fresh on every
|
Package identity issues Section 5.3 object ids: per viewer, fresh on every |
|
spellbench/internal/testcorpus
Package testcorpus shares one corpus registry across a test binary.
|
Package testcorpus shares one corpus registry across a test binary. |
|
spellbench/internal/testgame
Package testgame drives real gorge games for tests.
|
Package testgame drives real gorge games for tests. |
|
spellbench/mapping
Package mapping turns one gorge decision into a transaction of v2
|
Package mapping turns one gorge decision into a transaction of v2 |
|
spellbench/minihost
Package minihost is an in-process Spellbench v2 host for this adapter's
|
Package minihost is an in-process Spellbench v2 host for this adapter's |
|
spellbench/neutral
Package neutral lets gorge's policies play a protocol v2 game hosted by another engine (mtg-kernel on pauper-kernel-v2).
|
Package neutral lets gorge's policies play a protocol v2 game hosted by another engine (mtg-kernel on pauper-kernel-v2). |
|
spellbench/observe
Package observe builds the Section 6 observation for one seat from gorge's
|
Package observe builds the Section 6 observation for one seat from gorge's |
|
spellbench/protocol
Package protocol holds the Spellbench v2 wire types this engine emits and reads.
|
Package protocol holds the Spellbench v2 wire types this engine emits and reads. |
|
spellbench/seat
Package seat adapts a Spellbench v2 stdio agent to gorge's seat.Seat contract, so a v2 bot can play at an ordinary gorge table.
|
Package seat adapts a Spellbench v2 stdio agent to gorge's seat.Seat contract, so a v2 bot can play at an ordinary gorge table. |
|
spellbench/secrets
Package secrets implements the HMAC constructions of Spellbench v2
|
Package secrets implements the HMAC constructions of Spellbench v2 |
|
spellbench/session
Package session runs one v2 game over a gorge engine.
|
Package session runs one v2 game over a gorge engine. |
|
spellbench/validate
Package validate is a Go subset of the Section 11.3 live validator, used by
|
Package validate is a Go subset of the Section 11.3 live validator, used by |
|
spellbench/wire
Package wire holds the transport rules of Spellbench v2 Section 2 and the
|
Package wire holds the transport rules of Spellbench v2 Section 2 and the |
|
spellbench/xview
Package xview builds x_gorge_view_v1: gorge's own seat view and native
|
Package xview builds x_gorge_view_v1: gorge's own seat view and native |
|
testkit
|
|
|
bench
Package bench is the policy-agnostic, head-to-head game matrix shared by the bot benchmark and policy-tuning tools.
|
Package bench is the policy-agnostic, head-to-head game matrix shared by the bot benchmark and policy-tuning tools. |
|
paymirror
Package paymirror is an A/B differential check for cast payment plans (docs/design/2026-09-24-cast-payment-plans.md §10: "compare a manual execution of the same selected payment with planned execution for state equivalence").
|
Package paymirror is an A/B differential check for cast payment plans (docs/design/2026-09-24-cast-payment-plans.md §10: "compare a manual execution of the same selected payment with planned execution for state equivalence"). |
|
testutil
Package testutil holds fixtures and checks shared by tests that sit outside the rules package's own test binary -- Task 26's acceptance harness and engine/rules/fuzz_test.go's invariant gate both need this without rules importing itself, so this package sits beside state and decision in the dependency order (cards -> state -> decision -> events -> effects -> rules -> view -> seat -> replay -> cmd/*) and imports only cards, state and decision (Ruling P9/P10).
|
Package testutil holds fixtures and checks shared by tests that sit outside the rules package's own test binary -- Task 26's acceptance harness and engine/rules/fuzz_test.go's invariant gate both need this without rules importing itself, so this package sits beside state and decision in the dependency order (cards -> state -> decision -> events -> effects -> rules -> view -> seat -> replay -> cmd/*) and imports only cards, state and decision (Ruling P9/P10). |
|
testutil/feedback
Package feedback loads a feedback snapshot directory — the match.json / log.json (plus optional view.json / report.json) files the server's feedback capture (task fbrepro1) writes beside a bug report — back into the (events.Log, rules.Config) pair a deterministic replay needs, and drives that replay to a chosen intent.
|
Package feedback loads a feedback snapshot directory — the match.json / log.json (plus optional view.json / report.json) files the server's feedback capture (task fbrepro1) writes beside a bug report — back into the (events.Log, rules.Config) pair a deterministic replay needs, and drives that replay to a chosen intent. |
Click to show internal directories.
Click to hide internal directories.