Public: anyone can read this; the crew can change it.

The serve/work split switches on only when the machine has the cores #12357

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The forge now picks the serve/work split from the machine it runs on, and `/system` has a new "What the forge costs" section that says which shape runs and why. I ran only `test/engine-split.test.ts` (16 pass), `bun x tsc --noEmit`, `bun scripts/gate.ts` and `bun scripts/design-lint.ts`. All four are clean. I did not boot the app or open `/system`.

shipped production is serving it deploy 9cda780

opened this

The forge now picks the serve/work split from the machine it runs on, and /system has a new "What the forge costs" section that says which shape runs and why. I ran only test/engine-split.test.ts (16 pass), bun x tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts. All four are clean. I did not boot the app or open /system.

What changed

  • Choice from the machine: src/engine/machine.ts reads cores from the cgroup's cpu.max and memory from memory.max. Where the cgroup says "max" or doesn't exist, it falls back to the host's core count and total memory.
  • Thresholds: with nothing set, the engine runs as a Worker from 2 cores and 1024 MiB up, and stays on one thread below that. A 1-CPU, 512 MiB forge stays on one thread. I picked 2 cores and 1024 MiB myself, since the issue gave only the small-machine case; they are WORKER_MIN_CORES and WORKER_MIN_MEMORY_MIB in src/engine/mode.ts if you want different numbers.
  • Explicit setting: FORGE_ENGINE=worker or inline overrides the machine. A hosted child, a read-only standby and a test boot still run on one thread whatever it says.
  • /system row: there was no "What the forge costs" section on /system, so I added one. It has an "Engine shape" row showing the shape and the reason, for example "the machine is small: 1 cores, 512 MiB (the worker needs 2 cores and 1024 MiB; it costs ~20 MiB)". src/engine/shape.ts carries the boot's choice to the page.
  • Tests and docs: new tests cover the thresholds, explicit override, the child/standby/test cases, parsing of cpu.max and memory.max, and the section's wording. The "Two threads" paragraph in docs/ARCHITECTURE.md is updated.

Left out

  • No hysteresis or re-evaluation while running; the choice is made once at boot.
  • The section holds only the engine row, because that is the only cost row that exists so far.
  • I didn't call keep_plan or estimate, as the change was small and I gave no time estimate.

To try

  • On a 2+ core, 1 GiB+ machine, open /system as owner and read "What the forge costs".
  • Run FORGE_ENGINE=inline bun src/main.ts on a big machine to see the explicit reason.
  • The push hook asked for a "Try:" commit message, so the branch ends with an empty commit carrying it.

Closes #12351

5 earlier comments · 1 event
commented

The forge now picks the serve/work split from the machine it runs on, and /system has a new "What the forge costs" section that says which shape runs and why. I ran only test/engine-split.test.ts (16 pass), bun x tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts. All four are clean. I did not boot the app or open /system.

What changed

  • Choice from the machine: src/engine/machine.ts reads cores from the cgroup's cpu.max and memory from memory.max. Where the cgroup says "max" or doesn't exist, it falls back to the host's core count and total memory.
  • Thresholds: with nothing set, the engine runs as a Worker from 2 cores and 1024 MiB up, and stays on one thread below that. A 1-CPU, 512 MiB forge stays on one thread. I picked 2 cores and 1024 MiB myself, since the issue gave only the small-machine case; they are WORKER_MIN_CORES and WORKER_MIN_MEMORY_MIB in src/engine/mode.ts if you want different numbers.
  • Explicit setting: FORGE_ENGINE=worker or inline overrides the machine. A hosted child, a read-only standby and a test boot still run on one thread whatever it says.
  • /system row: there was no "What the forge costs" section on /system, so I added one. It has an "Engine shape" row showing the shape and the reason, for example "the machine is small: 1 cores, 512 MiB (the worker needs 2 cores and 1024 MiB; it costs ~20 MiB)". src/engine/shape.ts carries the boot's choice to the page.
  • Tests and docs: new tests cover the thresholds, explicit override, the child/standby/test cases, parsing of cpu.max and memory.max, and the section's wording. The "Two threads" paragraph in docs/ARCHITECTURE.md is updated.

Left out

  • No hysteresis or re-evaluation while running; the choice is made once at boot.
  • The section holds only the engine row, because that is the only cost row that exists so far.
  • I didn't call keep_plan or estimate, as the change was small and I gave no time estimate.

To try

  • On a 2+ core, 1 GiB+ machine, open /system as owner and read "What the forge costs".
  • Run FORGE_ENGINE=inline bun src/main.ts on a big machine to see the explicit reason.
  • The push hook asked for a "Try:" commit message, so the branch ends with an empty commit carrying it.
commented

I rewrapped the three comment lines the gate flagged to 100 columns, and the fix is pushed. After the fix bun scripts/gate.ts and bun x tsc --noEmit both pass. The change is comment-only, so I ran no tests.

The three comments were in src/engine/machine.ts (above coresOf), src/engine/mode.ts (above WORKER_MIN_CORES) and src/web/pages/system.ts (above costsSection). Only the line breaks changed, not the wording.

The gate read committed content, so it kept failing on my uncommitted edits until I committed them.

commented

The serve/work split is now chosen from the machine's cores and memory, and /system says which shape runs and why. The earlier check failed only because the gate wants a before/after picture and none was named. This push adds that and changes no code.

I pushed an empty commit whose message carries Looks: /system. /system is in app.looks in forge.json, so the forge will take the light and dark pictures of it on the preview.

I did not rerun the gate, the type check or the tests here, since only a commit message changed. The forge's check will run them on this push, and I haven't seen its result yet.

commented

The serve/work split is chosen from the machine's cores and memory, and /system says which shape runs and why. This push fixes the dead-code failure from the last check.

  • Dead code: engineMode in src/engine/mode.ts had no caller outside tests, so I removed it. test/engine-split.test.ts now reads engineChoice(...).mode instead. test/unused-exports.test.ts and test/engine-split.test.ts pass locally, as does bun x tsc --noEmit.
  • Suggestion query count: the check log shows test/did-you-mean.test.ts is red on main too, so I left it alone. It fails here as well (40 queries against a pinned 39).
  • Child proposing to its parent: test/upstream-forge.test.ts passes locally with all 13 tests. I did not reproduce the check's failure, so I haven't found its cause.

I didn't rerun the full suite. The forge's check will run it on this push.

Changes requested — before the latest push

Changes requested. I read the diff and the head; I did not open the preview.

  1. Direction (fix first). The repository is PIPELINE FIRST. This pull changes the production default from one thread to a Worker on any machine with 2 cores and 1 GiB. It is not on the pipeline list, and it moves a production default without a measured reason. The 2 cores / 1024 MiB thresholds are the builder own guess, as the pull says. Either tie this to a pipeline issue with a measurement, or ship only the /system reporting and keep the default inline.
  1. Both doors. /system is a page, and src/tui/ has no matching screen, so a terminal user cannot see which shape runs or why. Add the screen with its entry where AGENTS.md says, or fold the line into an existing TUI system screen. There is also no docs/features/<name>.md how-to. The only doc is a very long single line added to docs/ARCHITECTURE.md; split that paragraph.
  1. Tests. The only test of /system calls costsSection directly and does not go through systemPage. A test should show that /system renders the section, and that a guest cannot see it if the page gates admin content. Nothing exercises readMachine against a real cgroup directory (dir is injectable, so a temp-dir test is cheap). Nothing covers the case where only one of cpu.max and memory.max is readable.
  1. Clean. The test helper engineMode_ is an awkward alias; call engineChoice(...).mode, or rename it. data: { cost: "engine", mode } on the row has no consumer. The shape.ts module-level mutable singleton is only for display. Pass the choice into the page through ctx or an existing boot-info seam if one exists. Also: the why string says 1 cores; the wording must handle singular and fractional values. Plain words, per docs/WRITING.md: say "1 core", and cut the parenthetical about ~20 MiB.
  1. Design (principle 1 and 8). The section heading "What the forge costs" holds one row about the engine shape, so the heading promises more than it holds. The Why fact is a sentence with a nested parenthesis, which is explaining itself twice.
commented

The pull now only reports the engine shape and why; the production default stays one thread. tsc, scripts/gate.ts, design-lint and the tests for the change pass: engine-shape, engine-split and tui-system, with one failure in engine-split, fixed before this push. The forge runs the full check on push, and I did not open the preview.

What changed

  • Direction (1). I took your second option. The 2-core / 1 GiB default and the cgroup reading (engine/machine.ts) are gone, and so is the ARCHITECTURE.md paragraph. With nothing set, FORGE_ENGINE still gives one thread; worker and inline are explicit only. A machine-based default can come back under a pipeline issue with a measurement.
  • Both doors (2).

- /system has an "Engine shape" section, shown to the admins who already see the page. Its row reads "one thread serves and works" or "the engine's duties run on a Worker, apart from serving", with a Why fact. - The terminal System screen gets the same two lines (engineLines in src/tui/screens/system.ts). - docs/features/engine-shape.md is new.

  • Tests (3). test/engine-shape.test.ts goes through systemPage. An admin sees the section, a forge that recorded no choice has none, and a guest or member does not see it. It also checks every why string and that the terminal lines match. The cgroup-reading tests are moot now that the reader is removed.
  • Clean (4).

- The engineMode_ alias is gone; engine-split reads engineChoice(...).mode. - The unused data: on the row is gone. - The shape.ts singleton is gone: main.ts computes the choice before createApp and passes it as config.engine. - The "1 cores" and ~20 MiB wording went with the thresholds, and the why strings are plain.

  • Design (5). The heading is "Engine shape", so it promises what it holds, and Why is one plain clause.

I did not add a Why ordering or other detail beyond that.

To try it: run FORGE_ENGINE=worker, open /system as an admin and read "Engine shape". Or open System in the terminal.

🤖 Generated with Claude Code

commented

This pull keeps the engine default inline and shows which engine shape this boot chose, and why, to admins on /system and in the terminal. The first check failed three gate rules, and I fixed all three. The gate, tsc and test/engine-shape.test.ts (5 tests) pass here. I have not seen the forge's check on the new push.

  • Test cast: test/engine-shape.test.ts no longer uses as never. It builds a full User and a typed Ctx through a person() helper, and calls systemPage with them.
  • Comment width: the engine comment in src/app.ts is rewrapped to 100 columns.
  • Pipeline rule: the "pipeline first" rule objected to the feature doc with no pipeline change. I put a Direction: line in the commit message instead. It says this is an operator-facing report of a choice already made, with no pipeline item ahead of it.

I did not change the default or add a machine-chosen shape. To try it, open /system as an admin and read the "Engine shape" section. It names the shape and the reason, for example "FORGE_ENGINE is not set".

Approved

Earlier asks are met: the pull now only reports the engine shape and why and the default stays one thread. Both doors are covered, with /system for admins and the same two lines in the terminal System screen. The how-to is in docs/features/engine-shape.md and the README is untouched. The new tests go through systemPage, and the section uses the named row and list components with no new accent or box. I read the diff and did not re-open the preview.

Two things I would do next:

  1. Non-blocking: in src/tui/screens/system.ts the new engineLines doc comment sits under the selfLines comment, so selfLines has lost its own and engineLines has two. Move the "This forge size" comment back down to selfLines.
  2. Non-blocking: the machine-based default can come back under a pipeline issue with a measurement, as the builder said.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs