Hydration

Hydration

Exedra is generated. Nobody assembles it by hand, and nobody edits the generated parts in place.

The problem hydration solves

A contributor certifies a pack against the engine in this repository. The venue then scores real episodes against the engine in its own. If those two copies ever differ, a pack passes its gate on a contributor's machine and behaves differently at the venue.

That failure is silent. No error is raised, no test goes red, and the first symptom is a score nobody can explain. It is the worst class of bug this project can have, because the platform's entire claim is that a stored score can be reproduced from a log.

Hand-maintaining two copies of the same file is how that happens. So there are not two copies. There is one source and one generated artifact.

How it works

An export tool runs in the platform's own continuous integration. It copies the shared parts into this repository, and opens a pull request whenever they drift.

The generated set is the four things that determine a score:

• the engine
• the scoring function and star rules
• the scenario pack schema
• the acceptance gate, together with the exact optimizer

A test in this repository asserts that each generated file is byte-identical to what the export produces. The test fails if anyone edits one here.

What this means for you

Do not edit the generated files. A pull request that changes them is refused on principle rather than on merit, because merit is not the question. Even a correct improvement, applied here, creates the drift the whole arrangement exists to prevent.

Improvements to the engine go upstream. Open an issue describing the behaviour you think is wrong, ideally with a scenario pack that demonstrates it. A pack that makes the engine produce an indefensible result is the most useful bug report this project can receive, because it is executable.

Everything else here is ordinary. Documentation, tutorials, prompts, context files, tooling around the gate, the local runner, and contributed packs are all normal contributions. Edit them freely.

Why the packs are copied too

The two shipped packs are generated by the same mechanism, for a smaller reason: they are quoted. The engine documentation uses their real battery and efficiency numbers in its worked examples. If a pack changed here and not upstream, the examples would describe a scenario nobody plays.

Versioning across the boundary

The generated engine carries its engine_version, and so does every episode the venue stores. A contributor certifying a pack today can name the engine version that certified it. When the engine version moves, packs are re-verified rather than assumed.

That is also why this repository does not promise that a pack accepted under one engine version is accepted forever. It promises something more useful: that the gate you ran is the gate the venue ran, at the version you both ran it at.