Build and check a release from stages

eb release runs S:/eclipse-build/pipeline/release.py with every tool pinned. check tells you whether a set of stages fits together. build makes the new release tree. Neither publishes anything.

Checked against the code. Neither command was run for this page.

EB means py -3.12 -I -B S:/eclipse-build/eb.py.

Before you start

The base: the tree of the last published release, S:/souls-script-kt/output/eclipse-release-<base>/depth6-online-mods. Its parent folder must hold exactly one FILES-CHANGED-<base>.sha256.txt.
Every stage has a stage.json made by eb stage make (start-a-stage.md).
For a build: enough disk space (EB free). The new tree is a hardlink copy of the base, so only changed files cost space.

Steps

Check the stage set.

EB release check --base <base tree> --work <dir> --stages <stage.json or stage folder> ...

Argument	Meaning
`--base`	Required. The published tree to build on.
`--stages`	Required. One or more `stage.json` files or stage folders.
`--work`	Where `check-report.json` goes. Default `S:/souls-script-kt/.tmp/eclipse-next/pipeline-v2/check`.
`--ignore-merges`	Ignore declared merges, to see every raw overlap.

It prints note: lines, a FAIL: line per problem, and a summary: N stages, N file targets, N rowlists; N problems; report .../check-report.json. Exit code 1 when there are problems. The check does not apply rowlists and does not run the AI Lua budget; those happen in a build.

Optional: a dry build. It also runs the regulation chain and the merges, but does not touch the tree.
```
EB release build --base <base tree> --out <new tree> --version <v> --work <dir> --stages ... --dry
```

Build.

EB release build --base <base tree> --out S:/souls-script-kt/output/eclipse-release-<v>/depth6-online-mods --version <v> --work <dir> --stages <stage.json> ...

Argument	Meaning
`--base`	Required.
`--out`	Required. The new tree. Must be a new folder: not the base, not inside a stage folder, not a published release.
`--version`	Required. For example `0.0.106`.
`--stages`	Required.
`--work`	Work folder. Default `S:/souls-script-kt/.tmp/eclipse-next/pipeline-v2/work-<version>`.
`--dry`	Plan only; the tree is not touched.

The build runs as a 4 GB eb job, so it may wait for memory (run-heavy-jobs.md).

What `eb release` adds before release.py runs

The gate. Every stage must have a provenance block (see below).
Frozen stages. For check and build, every stage folder is frozen into the store and copied out to S:/eclipse-build-out/sets/stage-<hash>. The copy is hash-checked and release.py reads the copy. Editing a stage after that does not change what gets built. The folders work, scratch, tmp, _work and secret-looking files are left out. The copies are removed when release.py ends; the frozen sets stay in the store, named stage_<id>_<hash> in frozen/INDEX.tsv. It prints froze N stages into the store.
Pinned tools. Polish, RegQ, TableRows, IdReg, CastleVariants, the check scripts and the vanilla regulation come from tools/tools.toml and are built or restored first. EB tool env shows the paths.
A fixed regulation IV. EB_REG_IV defaults to content, so two builds of the same stages give the same regulation.bin bytes.

What the build does

In order; any failure stops with STOP: ... and exit code 2.

Re-verifies the base release's FILES-CHANGED list.
Loads every stage, checks every source file against its sha256, and every replaced file against the base.
Resolves overlaps: a target named by more than one stage must be identical bytes, a declared chain, or a declared merge.
Scans the rowlists for cells written by two stages.
Applies the rowlists in (order, stage id) order onto the base regulation, then a second pass that must be all already-applied, then readback, scope, duplicate-order, lot-chain and relic-vessel checks.
Runs declared merges.
Makes the tree: a hardlink copy of the base, with each changed file copied in.
Runs the AI Lua _G budget on the tree (fails above 3584 names) and the gaol drops check.
Writes the lists.

Where the result lands

--out is the tree (a depth6-online-mods folder). Its parent is the release folder, which gets:

File	What
`FILES-CHANGED-<v>.sha256.txt`	sha256 and path of every changed file
`changed-list.txt`	the changed paths
`assemble-manifest-<v>.tsv`	per changed file: status, source, how it was resolved, which stages
`RC-NOTES-<v>.md`	release candidate notes, per stage
`CHANGELOG-DRAFT-<v>.md`	a changelog draft from the stages' `changelog` lines
`release-plan-<v>.json`	the full plan
`checks/`	outputs of the checks (`chain.txt`, `ai-lua-budget.txt`, `gaol-drops.txt`, ...)

The last line of a good build starts with N files with link count 1 (...). Running the same build again gives the same tree and the same FILES-CHANGED bytes.

The tree has no mod/nr-redirect/eclipse_content.tag. That file is written at publish.

What goes wrong

Message	Meaning	Fix
`GATE FAIL <stage>: no provenance ...` then `STOP: N stage(s) not made the eclipse-build way`	The stage has no `provenance` block and the release is 0.0.89 or later.	Give the stage a `stage.toml` and run `EB stage make` on it.
`GATE FAIL <stage>: merge steps run tools that live only in .tmp / a scratchpad`	A merge step pins a tool under `souls-script-kt/.tmp` or a Claude temp folder.	Import the tool into `tools/` (use-shared-tools.md).
`GATE WARN ...`	The same findings for a release before 0.0.89, or with `EB_GATE=warn`. The build goes on.
`STOP: stage <id> changed while it was frozen`	Someone wrote into the stage folder during the freeze.	Run again.
`FAIL: STALE CHAIN <path>: ...`	A file names a `base_stage`, and that stage is not in the release or now ships a different file.	Rebuild the later stage on the current file, run `stage make` again, or add the base stage to `--stages`.
`FAIL: OVERLAP <path>: ...; no merge declared`	Two stages ship different versions of one file and neither is built on the other.	Chain one on the other with `base_stage`, or declare a merge.
`FAIL: <path>: <stage> was built on <sha>, the base has <sha>`	The stage replaced a file that is different in this base.	Rebuild the stage on this base.
`FAIL: <stage>: <path>: source sha differs from the manifest`	A staged file changed after `stage make`.	Run `stage make` again.
`FAIL: DELROW CONFLICT ...`	One stage deletes a regulation row that another writes.	Settle it between the two stages.
`FAIL: RELIC VESSELS: ...`	The stage set changes the count of relic vessel rows. That would reset every player's relic loadouts and presets.	Do not add or remove those rows.
`STOP: ...: skipped N line(s): the cell does not hold the old value the list expects`	A rowlist was made on other values than this chain has.	Regenerate the rowlist on this base.
`STOP: ...: set N, the stage expects M` (or `added`)	The list did not do what `expect` says.	Fix the list or its `expect`.
`STOP: --out ... is a published (or foreign) release`	`--out` holds a content tag, another version's `FILES-CHANGED`, or publish logs.	Build into a new folder.
`STOP: AI Lua _G budget FAIL ...`	The tree's AI scripts define too many global names. There is no override.	Reduce the AI scripts; see `checks/ai-lua-budget.txt`.
`STOP: gaol drops: ...`	A placed evergaol boss does not drop its signature weapon.	See `checks/gaol-drops.txt`.
`STOP: base changed during the build`	Something wrote into the base tree.	Find what did; never build while a publish runs.

A build that stops on N problems in the stage set lists each one as a FAIL: line above it and in <work>/check-report.json.

Environment switches

Variable	Effect
`EB_GATE`	`warn`: the provenance gate only warns. `fail`: it always fails. Unset: fails for a target version of 0.0.89 or later. Emergency use only; say so in the release notes.
`EB_REL_JOBS`	How many RegQ / Polish runs go at once. Default 4. `1` runs them one after another, for debugging.
`EB_REL_CHAIN`	`0` applies each rowlist in its own Polish process (the old path). Default: one process per run of consecutive Polish lists.
`EB_REG_IV`	`content` (the default under `eb release`): the IV comes from the regulation's content. 32 hex digits: that IV, to reproduce a published file byte for byte.
`EB_HASH_JOBS`	Threads for hashing while freezing stages. Default 4.
`EB_DCX_JOBS`	Files `eb dcx` handles at once. Default 4.

The target version for the gate is --version for a build. For a check it is the first stage's base_release plus one.