fix(engine): move standing prose to docs so the engine can launch again - #184
Merged
Conversation
The Workflow tool refuses any script file of 512 KiB or more, and refuses it at launch. v0.2.0 shipped at 556,668 bytes, 32,380 past that line, with node --check passing, all 737 tests passing, and CI green. The released engine could not be run. Move 36 blocks of standing commentary verbatim into docs/architecture/engine-internals.md, keeping the opening sentence and a pointer at each site. The engine is now 465,677 bytes with 58,611 to spare. Add the guard that catches it next time: lint-engine.js fails at the cap and warns on stderr, without failing, past 92% of it. Also switch tests/sandbox-lint.test.js from execFileSync to spawnSync, since the old helper reported an empty stderr on every passing run and could not observe a warning that exits 0.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The problem
The Workflow tool refuses any script file of 512 KiB or more, and it refuses it at launch. v0.2.0 shipped at 556,668 bytes, 32,380 past that line, with
node --checkpassing, all 737 tests passing, and CI green. The released engine could not be launched at all.Found when batch 2 of the gate-hygiene work failed to start against current
main.The fix
36 blocks of standing commentary, the ones explaining why a helper is shaped the way it is rather than what the next line does, moved verbatim into a new
docs/architecture/engine-internals.md. Each site keeps its opening sentence and gains a pointer to the section carrying the rest.The headroom is deliberate: #167 and #168 both add engine code.
The guard
scripts/lint-engine.jsnow fails when the engine reaches the cap and warns on stderr, without failing, once it passes 92% of it. It sits beside the sandbox-construct rules for the same reason those exist: the constructs are legal JavaScript and the size is a legal file, and both only bite at runtime.Five tests cover it, including one asserting the real engine is under the cap.
Two test changes worth reading
tests/sandbox-lint.test.jsusedexecFileSync, which returns stdout only, so its helper hardcodedstderr: ''on every passing run and could not have observed a warning that exits 0. NowspawnSync.tests/sanitize-tasks-arity-guard.test.jssubtracted a baresanitizeTasks()doc-comment mention before counting real call sites. That prose moved to the docs page, so the guard now asserts its absence and expects 3 occurrences instead of 4. The arity check itself is unchanged in strength.Verification
Frozen architecture prose untouched;
tests/architecture-provenance.test.jsgreen.CLAUDE.md/AGENTS.mdfreeze pair kept byte-identical.