Extract a shared Factorio oracle CLI

[wormeyman]

Summary

Four repos now run the Factorio game headless to ask it questions. Each one wrote
the same plumbing from scratch. The plan is to pull that plumbing into one shared
Rust CLI, factorio-oracle, in its own repo.

This issue records what that means for FactorioTools. Nothing here changes
existing code. The agreed migration rule is "new probes only": the tool gets used
by the next capture anyone writes, and tools/ stays as it is until someone has a
reason to touch it.

The four repos are FactorioTools, factorio-blueprint-editor, FactorioMapWebUI and
FactorioWikiDamageThresholds. Each is getting its own issue.

Why

Measured, not estimated:

Repo	Oracle tooling	Lines	Install discovery
FactorioTools	tools/capture-factorio-oracle.sh + trim-factorio-oracle.py	421	own copy
factorio-blueprint-editor	tools/oracle/, 18 probes	7,900	own copy x18
FactorioMapWebUI	test/oracle/	9,504	own copy

A fourth copy turned up in an unrelated WordPress theme repo, in a Factorio
benchmark script that had been committed there by accident. It has since been
removed.

A real bug this work found

runtime-api.json does not contain the values of defines. Across all 1,554
define entries the only keys are name, order and description. There is no
value field at all.

tools/trim-factorio-oracle.py:150 does this:

return {v["name"]: v["order"] for v in define.get("values", [])}

So it uses declaration order as if it were the runtime value. It is correct today
only because Factorio declares directions clockwise from north = 0, which makes
order and value the same for a sequential enum. The committed fixture matches the
real numbers, so this is not a live defect in output.

But the docstring above it says defines.direction is "the authoritative answer to
'what number means east'". That claim is now false. It is an inference, and nothing
documents order as the runtime value.

The irony is worth stating plainly: direction encoding is the exact constant that
silently broke in 2.0, and it is the one the oracle infers rather than reads. Only
the running game knows that defines.direction.east == 4. Reading it properly
needs a probe mod, which is capability this repo has used and does not have - see
below.

Worth fixing whether or not the shared tool happens.

A documentation error

CLAUDE.md says the capture pulls four sources, and lists data/changelog.txt as
one of them. It pulls three. There is no changelog handling anywhere in tools/.
The changelog is a research source a human reads; it was written into the table as
if it were automated.

What this repo would hand over

Roughly 80% of the 421 lines. All of it is generic:

• Install discovery, including the macOS .app versus Linux directory layouts
  (capture-factorio-oracle.sh:71-107)
• Version derivation from --version, plus deriving the major.minor a mod's
  info.json needs
• The empty mod directory and its mod-list.json (:121-122)
• Finding the user data directory that script-output/ lands in (:140-154)
• Reading data/*/migrations/*.json into a rename table
  (trim-factorio-oracle.py:154-175). Nothing in it knows about oil fields.
• Pulling a named defines table out of runtime-api.json, generalised so the
  shared tool is not hardcoded to direction
• find_prototype's type search and its collision-box disambiguation (:95-114).
  This is the most reusable piece here. Most of these names exist twice, once as
  the placeable entity and once as the carried item, and
  data.raw["item"]["pumpjack"] has none of the geometry.
• Deterministic output and the --check drift mode

Two guards here are better than what the other repos have, and become shared
defaults:

• The dump mtime check (:124-126 and :156-168). A dump written before this
  run is left over from an older capture. Trimming it anyway would stamp stale
  prototype data with the version of the game that just ran, which is the exact
  silent pass the tool exists to prevent.
• The loaded-mods report (:136-138). Mods rewrite prototypes freely, so a
  capture that loads them describes one person's game. In the shared tool this
  should be a hard assertion against an expected set, not an echo a human has to
  read.

What stays here

• WANTED_ENTITIES (trim-factorio-oracle.py:30-41). These ten names are exactly
  EntityNames.Vanilla, one for one. A blueprint editor wants hundreds; a map tool
  wants none of them. The allowlist becomes caller-supplied config.
• WANTED_FIELDS and WANTED_CONNECTION_FIELDS. supply_area_distance,
  maximum_wire_distance and max_underground_distance are what OilFieldOptions
  encodes.
• Every assertion in FactorioOracleTest.cs.

Two rules the shared tool must not break

Raw values only, never derived. The docstring at trim-factorio-oracle.py:11-21
is what makes this fixture trustworthy. Factorio's rule for turning
supply_area_distance into covered tiles is not one formula - poles come out as
2*distance, a beacon as 2*distance plus its own footprint, and substation fits
neither. A guessed formula in a fixture would be confidently wrong and drift
invisibly. Note the tests already do derive things, but they do it where a wrong
derivation fails loudly against a hardcoded value, not in the fixture where it
would sit silently.

Byte-for-byte determinism. --check is a diff -u against a committed file.
Rust's serde_json does not sort maps, and HashMap order is randomised per
process. The shared tool needs BTreeMap or explicit sorting, indent=2, and a
trailing newline. Float formatting is the trap: 0.29, 2.5, 1.5 and 0.2 all
appear in the fixture, and any printer difference from Python turns every future
--check into permanent false drift. Test the Rust output against the current
committed fixture byte for byte before adopting it.

What this repo would get

A probe-mod mode it has used and does not have. The mod that established the
2.1 direction table, the mirror field and the Version bit layout was written,
run, and thrown away. The resulting blueprint string was pasted into
ParseBlueprintTest.cs and the generator discarded. Regenerating that fixture
today means rebuilding the mod from a paragraph of prose in CLAUDE.md. That is the
strongest single argument for the tool in this repo, and it is also what would fix
the defines problem above.

Three run modes rather than one. --dump-data here needs no mod at all - the
mod directory exists only to be empty. That is a contamination control, not a
scaffold. Two of the three sources need no game at all: migrations and
runtime-api.json are read straight off disk, and wube/factorio-data has
byte-identical migrations, so renames can be checked with no install.

Reference syncing, which this repo has never had. ~/GitHub/factorio-data is
used by hand here and named only in docs.

Prior art checked

Nothing existing covers this. Four projects re-implement Factorio's data stage in
embedded Lua (YAFC, factorio-draftsman, KirkMcDonald/factorio-tools,
factorio-scanner). They are fast and CI-friendly, and they are all approximations.
YAFC ships the warning itself: "YAFC loads mods in environment that is not
completely compatible with Factorio."

factorio-rust-tools is the closest match. Its CI downloads a pinned headless
Factorio from factorio.com/get-download/<version>/headless/linux64 and diffs
against a committed 37 MB golden file. That contradicts the line in CLAUDE.md
saying CI machines "have no Factorio install and never will", and it is a real
option for closing the gap the design doc already names: nothing automatically
notices a new Factorio release.

Also confirmed: --dump-data-raw is not a real flag, so --dump-data here is
correct. And capturing real exported blueprint strings by running the game has no
prior art anywhere, on two independent search passes.

Status

Design is agreed in outline: a Rust CLI, JSON in and JSON out, in a new public
repo. The write-up is not finished, and this issue will be updated with a link.

Separately, moving these repos under the FactoryGameFan org is proposed and not
decided. Nothing should be changed on that basis yet. One caution specific to
this repo: joelverhagen/FactorioTools#10 is open, cross-repository, with head
wormeyman:main and 466 files. What happens to a cross-repo pull request when the
head repo is transferred is not covered anywhere in GitHub's documentation. The
docs cover deleting a fork (pull requests permanently deleted) and detaching one
(pull requests lost), but not transfer. So this repo should move last, if at all,
and only after that question is settled.

Related issues

One per affected repo, all describing the same shared tool:

• Extract a shared Factorio oracle CLI factorio-blueprint-editor#235 - 18 probes, 1,071 lines of repeated plumbing, and the interactive probe that shaped the runner's interface
• Extract a shared Factorio oracle CLI FactorioMapWebUI#232 - the four duplicated wiring copies, the missing timeout, and the factorio-data tag contention
• Extract a shared Factorio oracle CLI FactorioWikiDamageThresholds#11 - a 21.3 MB truncated, unstamped game dump feeding public wiki pages

[wormeyman]

The `defines` finding described above is now tracked separately in #83, with the verification done against the installed 2.1.14 runtime-api.json: 0 of 1,408 define values carry a value field, and order is a dense 0..n-1 index across all 137 define tables. It is a wrong method producing a right answer today, and it stands on its own regardless of whether this shared-CLI work happens.

[wormeyman]

Status: the tool is built and the build order is done

FactoryGameFan/factorio-oracle is public, CI is green, and 167 tests pass. Nothing here changes the migration rule: it is still new probes only, and nothing in this repo needs to move.

What works today:

• factorio-oracle installs list - finds every install, reports both version forms and the three paths each one needs.
• factorio-oracle run --probe spec.json - five run modes (dump-data, create, interactive, preview, read-only), each with its own success rule. Returns the work directory, not "the dump", so a probe that writes several files or appends JSONL across a session works without special handling. Isolated config.ini per run, so a stale dump from an earlier capture cannot be picked up. There is a timeout, which none of the four repos had.
• factorio-oracle trim - cuts a data.raw dump down to a caller-supplied slice, with --check for drift.
• factorio-oracle provenance check|report - records which Factorio each fixture came from, and checks the record stays honest.

Three documents now carry the probe-writing knowledge, in docs/: order-of-attack.md, method.md, and gotchas.md with roughly 40 entries. Every borrowed lesson names the repo and issue it came from.

Not built: refs (sync, grep at a tag, worktree, archive cache). It is the last item and it is not blocking anything here.

What is settled for FactorioTools specifically

The byte-for-byte gate passes. run then trim against a real 2.1.14 install reproduces the committed test/FactorioTools.Test/OilField/factorio-oracle.json exactly, and --check works in both directions. That was the gate on whether this tool could ever replace tools/capture-factorio-oracle.sh. It can. Whether it should is a separate call, and tools/ stays as it is until someone wants to touch it.

#83 is fixed in the oracle, not here. collect_directions reads order out of runtime-api.json as if it were the direction value. Verified on the installed 2.1.14: 0 of 1,408 define values carry a value field at all, and order is a dense 0..n-1 index, so it cannot express a gap, a duplicate or a non-zero start. It is right today only because Factorio declares directions clockwise from north = 0. A trim spec with defines_from: "probe" plus trim --probe-dump reads the real numbers from a running game. Confirmed to change no fixture bytes today, which is the ideal shape for that fix. The Python keeps the bug by design.

#81 was settled by a probe here, and merged as PR #90. examples/pumpjack-terminals places pumpjacks in all four rotations on both 2.0.77 and 2.1.14 and reads target_position off the runtime API. All four matched Helpers.cs on 2.0.77, which is what ruled out a broken probe; east and west disagree on 2.1.14.

Nothing to do here. This is a status update.

[wormeyman]

Correction: refs shipped, so the status above is out of date

The status comment above went up about four hours before refs merged. Two
things in it are now wrong.

• It says "Not built: refs". It is built. PR Guard against enabling beacons and heat pipes together (temporary) #10 merged as 6a6ddce on
  2026-08-17. It was the last item in the build order, so the tool is done.
• It says 167 tests pass. There are now 260: 247 unit and 13 integration.

I ran the full suite before writing this, and all 260 passed with none skipped.
That took setting both gate variables by hand. Left alone, two tests skip: one
wants FACTORIO_ORACLE_PROVENANCE_DIR, and one wants
FACTORIO_ORACLE_OLD_FACTORIO, meaning an install older than the crate's own
fixtures. Four more tests need a real Factorio, and four need a clone of
wube/factorio-data. Those gates are why a green run can prove less than it
looks, so it is worth saying which ones really ran.

What refs does

It reads Factorio's shipped Lua and its API docs at a version you name, and
it never moves HEAD in the shared clone. That is the whole point. One
clone of factorio-data sits on one branch, and several repos want to read
different versions of it.

Action	What it does
refs show <tag> <path>	Print one file at a tag
refs grep <term> --tag A --tag B	Search at one tag or several, and report a same-or-differs verdict
refs worktree <tag>	Make a real directory at a tag, for tools that need one. --remove cleans it up
refs docs <ver> <file>	Print a Lua API docs file. Reads an installed game before it touches the network
refs sync <ver> [--check]	Report whether a version's reference material can be read

show, grep and worktree need no Factorio installed. They need only the
clone. docs and sync do pick an install. A worktree costs 0.077 seconds and
8.6 MB, and two at the same tag can sit side by side.

What this changes here

The issue body names reference syncing as the one thing this repo has never
had, and says ~/GitHub/factorio-data gets used by hand and is named only in
docs. That is now a command rather than a habit.

Cross-version drift. The 2.1 direction table question in the body is the
shape refs grep was built for. Give it a term and two tags, and it prints the
hits per tag and then a verdict:

$ factorio-oracle refs grep damage_type --tag 2.0.77 --tag 2.1.14
2.0.77  base/prototypes/achievements.lua:438:    damage_type = "fire",
...
2.1.14  space-age/prototypes/tips-and-tricks.lua:347:      damage_type = "physical",

differs between 2.0.77 and 2.1.14

That is a real run from today, not a sketch. The verdict line is the part worth
having, because it answers the question without you reading the hits.

#83 is not solved by this, and I want to be clear about that.
refs docs 2.1.14 runtime-api.json hands you that file with no download,
because the installed game already ships it. It still will not answer the
defines question. I re-measured the installed 2.1.14 today while writing
this:

count	number
leaf entries under defines	1,408
tables carrying values	137
tables carrying subkeys	12
total entries	1,557
entries carrying a value field	0

Those numbers agree with the first comment on this issue, which reported 1,408
define values and 137 define tables. Both are right. 1,408 is the leaf count,
and 137 is the count of tables holding values. The 12 tables holding
subkeys make the total 149, and 1,408 plus 149 is the 1,557 above. Nothing in
the record needs correcting.

The finding is unchanged and it is the one that matters: not one entry
carries a value field. Reading order as the value is still a wrong method
that gets a right answer today, and it works only because Factorio happens to
declare its directions clockwise from north = 0 with no gaps.

The fix stays a probe, and run supports that directly with
defines_from: "probe".

The migration rule has not moved

Still new probes only. Nothing in this repo needs to change, and refs
does not change that either. It is a thing to reach for when you next want to
know what a version did, not a thing to port to.