Packages

Every Go package in gorge, with its purpose, size, importers and status, for a contributor looking for where something lives or whether a package is load-bearing. The guided tour of the tree, the import rules and "where does my change go?" are on Repository layout.

The tables below are generated from the source tree by cmd/pkgmap each time the site is built, so they never go stale. Tier and status come from one committed classification file, docs/site/architecture/packages.tiers.json; go run ./cmd/pkgmap -check (and the package's test) fails when a package is missing from it or an entry names a path that no longer exists.

Columns:

• Purpose: the first sentence of the package doc comment (or the classification's purpose when the package has none).
• LOC / Test LOC: non-test / test lines of Go in that directory (not recursive), counting every build tag.
• Imp: in-repo packages importing it from non-test code; +N adds the packages that import it only from tests.
• Status: CORE (the engine), SUPP (supports the product), EXT (optional extension: bots, search, ML, alternate wires), TOOL (tooling, tests, ratchets), SUSP (suspected obsolete) or RED (redundant). SUSP and RED entries are discussed on the cleanup roadmap.

The tier-dependency graph at the end is built from the actual imports, and flags any import from a tier into one listed after it.

For where a given kind of change belongs, see Repository layout.

To preview locally:

go run ./cmd/pkgmap > docs/site/architecture/_generated_packages.md

99 packages.

Engine (engine/): T0 card pipeline and T1 rules core

The card compiler, the event-sourced state, the rules engine, the per-seat view, replay, deck parsing and the Seat contract. Imports nothing outside engine/.

Package	Purpose	LOC	Test LOC	Imp	Status
engine/cards	Package cards compiles Forge card scripts into the engine's card IR.	16924	11031	49 +15	CORE
engine/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-oracl…	66	38	0	TOOL
engine/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.	3734	3158	41 +8	CORE
engine/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.De…	1102	1487	13 +4	CORE
engine/effects	Package effects implements the primitives Forge card scripts reference: the api: effects (DealDamage, Draw, ChangeZone, Pump, Token, ...), the filter language that matches cards a…	84381	69968	13 +3	CORE
engine/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 produc…	1333	295	3	CORE
engine/events	Package events defines every way state can change and is the only package permitted to mutate state.Game.	10869	4774	24 +9	CORE
engine/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.	353	911	9 +7	CORE
engine/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-b…	135317	456216	29 +18	CORE
engine/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 characte…	2322	350	2	CORE
engine/rules/combat	Package combat is attack and block legality: the CR 508.1/509.1 declaration predicates (CanAttack, CanAttackPair, CanBlock) and the requirement and restriction evaluation they dep…	1936	230	1	CORE
engine/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…	4026	639	5	CORE
engine/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 vo…	12821	378	1	CORE
engine/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-resul…	716	0	3 +1	CORE (no own tests)
engine/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 pri…	393	111	1	CORE
engine/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 pred…	6188	389	1	CORE
engine/seat	Package seat is who answers the engine's decisions.	51	0	19 +9	CORE
engine/state	Objects, zones, players, the Game and the continuous-effect vocabulary (no package doc yet).	6464	1488	48 +7	CORE
engine/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…	4941	7909	31 +7	CORE

Bots (bots/)

The bot policy board, the default heuristic bot, the bots registry and the hosted bots with their inference runtime (MCTS search, net forward pass, SpellBench builtins). Imports engine/ only.

Package	Purpose	LOC	Test LOC	Imp	Status
bots	Package bots is the registry of bot policies a host can link in.	590	407	14 +3	SUPP
bots/all	Package all links every built-in hosted bot policy.	10	127	4 +4	SUPP
bots/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 val…	6189	7133	2 +2	EXT
bots/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: unifo…	267	388	1 +2	EXT
bots/bot	Thin registration of a built-in policy in the bots registry.	44	181	3 +1	SUPP
bots/botpolicy	Package botpolicy holds the one bot decision policy, in one copy.	12485	15188	19 +7	CORE
bots/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 searc…	224	111	5 +1	SUPP
bots/forgeheuristic	Package forgeheuristic registers the Forge-derived experimental policy.	138	405	1	EXT
bots/gonet	(no package doc)	1150	404	0 +2	EXT
bots/gonet/gonettest	Package gonettest writes a tiny, deterministic network file for tests.	186	0	0 +2	TOOL
bots/heuristic	(no package doc)	2101	5444	18 +16	CORE
bots/lethalpressure	Thin registration of a built-in policy in the bots registry.	24	0	1 +2	SUPP
bots/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 padde…	1027	1112	0	EXT
bots/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-w…	8865	4892	7	EXT (linked into seat)
bots/sanity	Package sanity is the common-sense layer of the hand-written hosted bots.	325	338	3 +1	EXT
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-visibl…	174	441	1 +1	EXT
bots/searchprobe	Package searchprobe contains the experimental history-conditioned search harness.	9509	8781	8 +2	EXT (linked into host)
bots/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.	1318	2002	7 +2	EXT (linked into host)
bots/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.	184	336	0 +4	EXT
bots/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 p…	6090	1363	1 +1	EXT
bots/spellbench/payexec	Package payexec lowers a gorge payment plan onto the manual mana surface.	706	488	1	EXT
bots/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…	139	0	1	EXT

Server (server/)

The importable reference server (server/gorged), the host and its HTTP API, the wire protocol, the ManaBrew and SpellBench v2 adapters, and the divergence recorder.

Package	Purpose	LOC	Test LOC	Imp	Status
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).	512	589	2	SUPP
server/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 i…	105	0	1	EXT (linked into host)
server/gorged	(no package doc)	5358	9070	1	CORE
server/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 wid…	9422	18236	5 +1	SUPP
server/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 w…	1368	4879	2	SUPP
server/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…	1018	2468	1	EXT
server/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 p…	4328	4922	3	EXT
server/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 Tr…	2367	2475	1 +1	EXT
server/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-co…	528	229	4	SUPP
server/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 generat…	758	297	6 +2	SUPP
server/protocol/manabrew	Package manabrew defines the ManaBrew protocol's JSON wire types and codecs.	3154	678	3 +1	EXT
server/protocol/manabrew/internal/schemagen	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…	296	22	0	TOOL
server/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.	641	464	1 +1	EXT
server/spellbench/catalog	Package catalog holds the engine's catalog decks: the five Spellbench Pauper	160	154	4 +5	EXT
server/spellbench/env	(no package doc)	389	972	3 +2	EXT
server/spellbench/gamecfg	Package gamecfg builds a gorge engine whose every random draw comes from	111	262	4 +2	EXT
server/spellbench/identity	Package identity issues Section 5.3 object ids: per viewer, fresh on every	312	431	4 +1	EXT
server/spellbench/internal/testcorpus	Package testcorpus shares one corpus registry across a test binary.	23	0	0 +11	TOOL
server/spellbench/internal/testgame	Package testgame drives real gorge games for tests.	66	0	0 +4	TOOL
server/spellbench/mapping	Package mapping turns one gorge decision into a transaction of v2	2571	3444	5	EXT
server/spellbench/minihost	Package minihost is an in-process Spellbench v2 host for this adapter's	250	192	0 +3	EXT
server/spellbench/neutral	Package neutral lets gorge's policies play a protocol v2 game hosted by another engine (mtg-kernel on pauper-kernel-v2).	2355	939	1	EXT
server/spellbench/observe	Package observe builds the Section 6 observation for one seat from gorge's	670	812	6 +2	EXT
server/spellbench/protocol	Package protocol holds the Spellbench v2 wire types this engine emits and reads.	1432	1428	9	EXT
server/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.	1131	996	2 +1	EXT
server/spellbench/secrets	Package secrets implements the HMAC constructions of Spellbench v2	78	113	7 +1	EXT
server/spellbench/session	Package session runs one v2 game over a gorge engine.	906	813	1	EXT
server/spellbench/validate	Package validate is a Go subset of the Section 11.3 live validator, used by	584	962	1 +4	EXT
server/spellbench/wire	Package wire holds the transport rules of Spellbench v2 Section 2 and the	567	201	9 +1	EXT
server/spellbench/xview	Package xview builds x_gorge_view_v1: gorge's own seat view and native	545	429	4	EXT

Tooling (internal/, testkit/, cli/)

Module-private ratchets and code generators (internal/), plus the public test support, game runner and command-line layer that outside modules may import (testkit/, cli/). Shell and Python helpers live in scripts/ (contributor/CI); they are not Go packages.

Package	Purpose	LOC	Test LOC	Imp	Status
cli	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).	1373	505	0	TOOL
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 outs…	5	2080	0	TOOL (load-bearing)
internal/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 stil…	1472	1351	1	TOOL
internal/corpusheap	Heap-footprint ratchet (tests only).	0	242	0	TOOL
internal/testbudget	Package testbudget stores per-test-binary peak RSS records.	71	0	1	TOOL
internal/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 op…	1009	212	1 +1	TOOL
testkit/bench	Package bench is the policy-agnostic, head-to-head game matrix shared by the bot benchmark and policy-tuning tools.	1443	1686	4 +8	TOOL/SUPP
testkit/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 w…	4619	2064	2	TOOL
testkit/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 inv…	693	933	7 +35	TOOL
testkit/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…	498	368	2 +3	TOOL

Commands (cmd/)

Product and developer binaries. No package imports a command.

Package	Purpose	LOC	Test LOC	Imp	Status
cmd/cardfuzz	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…	2613	2303	0	TOOL
cmd/codeshape	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.Ho…	118	38	0	TOOL
cmd/deckimport	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…	867	550	0	TOOL
cmd/enginebench	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 an…	1970	221	0	TOOL
cmd/forgec	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.	496	214	0	CORE
cmd/gcgate	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.	246	106	0	TOOL
cmd/gentypes	Command gentypes writes web/src/protocol.ts from package protocol's structs.	101	271	0	TOOL
cmd/gorged	Command gorged serves bot tables, play-vs-bot and spectating to a browser: the reference server (server/gorged).	72	251	0	CORE
cmd/headdiff	Command headdiff shows WHAT moved a golden acceptance chain head, instead of four changed hashes.	310	129	0	TOOL
cmd/kcensus	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…	643	0	0	TOOL
cmd/keywordbench	Command keywordbench measures keyword presence separately from event-log use.	507	195	0	TOOL
cmd/mtgsim	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.	407	307	0	TOOL
cmd/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-su…	245	57	0	TOOL
cmd/pkgmap	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 m…	506	56	0	TOOL
cmd/repro	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…	701	1798	0	TOOL
cmd/spellbench-gorge-agent	Command spellbench-gorge-agent serves gorge's registered bot policies in the Spellbench v2 agent role over stdio.	129	0	0	EXT
cmd/spellbench-gorge-env	Command spellbench-gorge-env serves the Spellbench v2 environment role over stdio.	94	0	0	EXT
cmd/testbudget	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).	548	339	0	TOOL

Tier dependencies

Generated from the non-test imports (build tags ignored). An arrow points from the importing tier to the imported one and counts distinct package pairs; red arrows are back-edges, a tier importing one listed after it.

graph TD
  t0["Engine (engine/): T0 card pipeline and T1 rules core<br/>19 packages"]
  t1["Bots (bots/)<br/>22 packages"]
  t2["Server (server/)<br/>30 packages"]
  t3["Tooling (internal/, testkit/, cli/)<br/>10 packages"]
  t4["Commands (cmd/)<br/>18 packages"]
  t1 -->|66| t0
  t2 -->|89| t0
  t2 -->|20| t1
  t2 -->|1 back| t3
  t3 -->|21| t0
  t3 -->|8| t1
  t3 -->|2| t2
  t4 -->|50| t0
  t4 -->|15| t1
  t4 -->|12| t2
  t4 -->|16| t3
  linkStyle 3 stroke:#d32f2f,stroke-width:2px

1 back-edge import(s)

Importer	Imports	Tiers
server/spellbench/internal/testcorpus	testkit/testutil	server → tooling

Non-Go top-level paths

Path	What	Status
web/	Svelte+Vite client	SUPP
scripts/	contributor and CI helpers: CI sharding, smokes, enginebench, the docs sets renderer	TOOL
docs/	design docs (docs/design/), decisions (docs/decisions/), this site (docs/site/), an internal guide for AI coding agents (docs/agents/)	SUPP
.githooks/	opt-in git hooks: the package-classification check, the RACE=1 race gate	TOOL
.github/	the ci, docs, coverage and promote workflows, the PR template	TOOL

The research packages, draft events and the oracle pipelines are not in this repository and are not listed here; see The three repositories.