Skip to content

fix(engine): move standing prose to docs so the engine can launch again - #184

Merged
aaddrick merged 1 commit into
mainfrom
fix/engine-script-size-cap
Jul 28, 2026
Merged

fix(engine): move standing prose to docs so the engine can launch again#184
aaddrick merged 1 commit into
mainfrom
fix/engine-script-size-cap

Conversation

@aaddrick

Copy link
Copy Markdown
Owner

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 --check passing, 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.

before  556,668 bytes   32,380 over the cap
after   465,677 bytes   58,611 to spare

The headroom is deliberate: #167 and #168 both add engine code.

The guard

scripts/lint-engine.js now 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.js used execFileSync, which returns stdout only, so its helper hardcoded stderr: '' on every passing run and could not have observed a warning that exits 0. Now spawnSync.
  • tests/sanitize-tasks-arity-guard.test.js subtracted a bare sanitizeTasks() 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

node --check + lint-engine + bash -n + manifest JSON   pass
node --test                                            742/742
bash tests/setup-worktree.test.sh                       32/32

Frozen architecture prose untouched; tests/architecture-provenance.test.js green. CLAUDE.md/AGENTS.md freeze pair kept byte-identical.

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.
@aaddrick
aaddrick merged commit b591d71 into main Jul 28, 2026
1 check passed
@aaddrick
aaddrick deleted the fix/engine-script-size-cap branch July 28, 2026 17:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant