Define Engine, Harness and Host, enforce them in rulebooks, and rename the code to match - #104
Closed
vinniefalco wants to merge 12 commits into
Closed
vinniefalco wants to merge 12 commits into
vinniefalco wants to merge 12 commits into
Conversation
The root `AGENTS.md` now defines Engine, Harness and Host in one `## Definitions` section, with the words to use for every other meaning. Comments, docs, rulebooks and dated records now use "host" only for the application that runs prompts through the Harness, and name the Harness, the Lua globals, the real filesystem, machines and embedding parts with their own words. - Rulebooks lose the statements that called the Harness a host or fixed today's session bindings as rules: the pushed-binding and `LaunchOptions::vfs` invariants in `harness-sessions`, the binding and session-table invariants in `workshop-server`, and the `cancel::CancelHandle` invariant in `harness-runner`. - Code files change only in comments and Cargo `description` strings. No code file gains lines, and the `__impl_*.lua` preludes keep their line counts. - Guide headings in the old sense change, and their links follow, for example `#the-prompt-the-host-and-the-harness` and `#standard-lua-and-engine-calls`. The `guide/promptforge-*-guide.md` exports are regenerated. - Identifiers, test names and message strings that contain "host" do not change.
Prose that names the Engine or the Harness now writes the word capitalized, as the root `AGENTS.md` Definitions require. Each changed line differs from its old form only in letter case, and code files change only in comments and Cargo `description` strings. - Lowercase stays for crate names and paths (`harness-runner`, `promptforge-engine`), identifiers, string literals, quotations, and other senses such as the speech engine under `crates/gateway/stt/` and Rust's test harness. - The `guide/promptforge-*-guide.md` exports are regenerated from the changed chapters.
Some lines used "engine" or "harness" for one crate or for test scaffolding, where the capitalized defined term would read wrong. They now name the crate, the walk, the Engine version, or the test server. - `AGENTS.md` writes the single-public-crate pair as `promptforge` and `harness` and calls `promptforge-engine` the executor; `crates/promptforge-internal/engine/AGENTS.md` names the `promptforge-engine` module path. - The comments for the frontmatter major version in `prompts.rs`, `run-api.ts` and `build-frontmatter.rs` now name the `promptforge:` key. - Only comments change.
A new test in `docs-claims.mjs` reads every `AGENTS.md`, every `.cursor/rules` file, and the crate doc of every `lib.rs` or `main.rs` with `## Invariants`, and fails when one of them uses the three terms against the root `AGENTS.md` Definitions. Each finding names the file, the line, and the rule it breaks. - The test fails on lowercase "host", on lowercase standalone "engine" or "harness", and on retired phrases such as "production host"; inline code, fenced code, and the Definitions section are skipped. - Allowlists keep network and outside-tool phrases (`host-and-address`, self-hosted, GitHub-hosted) and other senses (speech engine, database engine, test harness); files under `crates/gateway/stt/` are exempt for "engine". - `AGENTS.md` names the test as the enforcement of its rules.
`HostBackend` serves real directories. It does not stand for the Host. `promptforge::vfs::HostBackend` is now `promptforge::vfs::RealBackend`, and the old name has no alias. The vfs module `host` is now `real`, and its helper types, locals and test text follow. - `HostAccess`, `HostRoot`, `identity_to_host`, `host_from` and `host_to` become `RealAccess`, `RealRoot`, `identity_to_real`, `real_from` and `real_to`. - The read-only error text now says "the real backend is read-only". The lint reason in `lib.rs` now says "an operating-system notion". - Tests that mounted a `MemoryBackend` at `/host` now use `/mount`. The Engine test `a_store_at_the_root_cannot_reach_a_mount_beneath_it` takes its new name from that mount. - `public-api.txt` changes only in the 7 `HostBackend` lines. `vfs.md` changes only in names and two comments, so a later page refresh is separate.
`vfs.md` is rewritten for the new name `RealBackend`. The page has three tours and 29 Reference entries, and each tour's example compiles as a doctest. The diff covers most of the file, because the page is written fresh. - Only `vfs.md` changes. No Rust source and no `public-api.txt` line changes.
The Lua module `host` installs the Engine's globals, so it never meant the Host. The module `host` is now `engine_globals`, and `inject_host`, `inject_host_with_var` and `install_host_apis` are now `inject_values`, `inject_values_with_var` and `install_engine_globals`. `HostGlobal`, `host_injected` and the Lua helper `host_type` become `EngineGlobal`, `values_injected` and `engine_type`. - Reserved-name errors now say "an Engine global" in place of "a host global", and the section VM errors say "Engine values". The parser contract tests, the prelude tests and the quotation in `02-file-structure.md` follow, and `promptforge-language-guide.md` is regenerated. - The registry key `promptforge.host.store_phase` is now `promptforge.engine.store_phase`. - The Lua-sense test names, the `expect` texts and the prompt names `shared-host` and `shared-host-load` take the same words. - Run behavior does not change. Only message text and the registry key string change.
`RunHost` stands in for the Harness in Engine tests, so its names now say Harness. `RunHost`, `run_with_host`, `run_host` and `delta_host` become `RunHarness`, `run_with_harness`, `run_harness` and `delta_harness`, and the module `host` in `test_support` becomes `harness`. Every local named `host` in the Engine crate follows. - Test names and messages that meant the Harness now say Harness, such as `a_chat_round_streams_its_deltas_to_the_harness` and the assert text "the Harness's table". - The doctest text in `effect.md`, `ids.md` and `transport.md` says Harness in the same places. The lint reason in `run.rs` now says "the public API". - Strings that mean the Host keep the word host, and so does one Host-sense test name. No test logic changes.
The runner's `performers-host.rs` holds `LogTaskEvents`, `TokioTimer` and `VfsStore`, which the runner supplies itself. The file is now `performers-builtin.rs`, and its module `host` is now `builtin`. In the Engine, `execute/engine.rs` is now `execute/walk_target.rs`, and the module `engine` is now `walk_target`. - Both file moves are pure renames, so file contents do not change. The re-exports `LogTaskEvents`, `TokioTimer` and `VfsStore` keep their paths. - In the `execute.rs` header, the `walk_target` bullet moves to its alphabetical place after `tools`, and `mod walk_target;` sorts after `tools`. - The four files that named `engine::` now name `walk_target::`.
The DOM element that holds a dialog or a panel is a container, not the Host. The `host` option of the modal and panel dialogs is now `container`, and `LazyPanelHost` is now `LazyPanelContainer`. The parameters and locals that hold that element take the name `container`, and the test helper `harness()` is now `setup()`. - `harness.mjs` in the gateway config UI is now `test-support.mjs`, and its test importers follow. - Check texts that named the Host now name the part: the chat box tests say "the owning part", the status bar tests say "the status bar", and the settings tests say "listener bind" in place of "hosting bind". The class `host-toolbar` is now `owner-toolbar`, and the unknown action `reboot-the-host` is now `reboot-the-machine`. - Every caller of the renamed option changes in this commit, so the TypeScript build has no old name left. Network host names are unchanged.
`SyntheticHost` in the `build-llama-cuda` tests models a Windows machine, so it is now `SyntheticMachine`, and `HOSTED_OFFER` in the Foundry provider is now `SERVED_OFFER`. Database errors in the `harness-log` and `workshop-workspace` tests now say database, and one gateway test says "the native speech engine". `RETIRED_SEEDS` grows from 8 to 17 names, so the retired-symbol scan rejects the old host names in live Engine source. - The root `AGENTS.md` drops the sentence that kept the old names until a rename landed, and "Cargo's host triple" now reads "Cargo's host and target vocabulary". - The seed test now matches the full seed name in each violation text. Under the old substring match, `inject_host` shadowed `inject_host_with_var`, so the test could not name the longer seed. - The retired names remain in `engine_guards.rs` as strings, because the scan needs them.
The deprecation text for the `[workshop]` section in `runner.rs` said the gateway "hosts" no workshop listener. It now says the gateway "runs" no workshop listener, so the word host keeps only the Host sense in this text. - Only the message text changes. No test asserts it.
vinniefalco
changed the title
This branch was successfully deployed
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
1 participant
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 words host, harness and engine had drifted: code, docs and rulebooks called the Harness "the engine's production host", so coding sessions read the Harness and the Host as one thing and built API layers on that. This PR gives the three words one meaning each, makes the rulebooks enforce it, and renames the code names and messages that still used "host" in another sense, so code and prose agree.
Breaking for Papergate:
promptforge::vfs::HostBackendis nowpromptforge::vfs::RealBackend, with no alias. Papergate must update its import.What changes
AGENTS.mdgets a## Definitionssection for Engine, Harness and Host, with the words to use for every other meaning (Engine globals, real files, machine, the embedding part, run/serve/embed/hold) and the names other tools define that stay as they are. The Roles bullets that restated the old meaning are gone.harness-sessions,workshop-serverandharness-runnerrulebooks and Invariants blocks; the other rulebooks are reworded.vibe/now use "host" only for the application. Five guide headings change, with their links.crates/workshop/ui/test/docs-claims.mjsnow fails when a rulebook (everyAGENTS.md, every.cursor/rulesfile, every## Invariantscrate doc) uses the words against the Definitions.Commits
Commits 1 to 4 are the prose, rulebook and guard work. Commit 2 is case-only by construction, so reviewing commit by commit is easiest.
Define Engine, Harness and Host and fix their use in prose: meaning fixes, about 520 files. Also adds the plan recordvibe/2026-09-30-1-engine-harness-host-terminology.md.Capitalize Engine and Harness in prose: case-only, 262 files.Reword prose that names one crate or test scaffolding: 11 lines.Guard the Engine, Harness and Host terms in rulebooks: the test.Commits 5 to 12 are the code renames, each with its own checks:
Rename HostBackend to RealBackend:HostBackendis nowRealBackend.HostAccess,HostRoot,identity_to_hostand thevfs::hostmodule change with it, and the mount fixtures in the tests use/mount. Also adds the plan recordvibe/2026-09-30-2-host-identifier-rename.md.Refresh the vfs facade page for RealBackend:vfs.md, rewritten for the new name by the page tool. This is a near-total rewrite of one page, so it is easiest to review on its own.Rename the Lua Engine-globals names:inject_hostisinject_values,install_host_apisisinstall_engine_globals,HostGlobalisEngineGlobal, and the modulehostisengine_globals. Reserved-name errors say "an Engine global" and the section VM errors say "Engine values". The guide quotation follows.Rename the Engine test-support Harness names:RunHostisRunHarness, and thehostlocals in the Engine tests areharness.Rename the internal modules named host and engine:performers-host.rsisperformers-builtin.rs, andexecute/engine.rsiswalk_target.rs.Rename DOM container and test-helper names in the UIs: the modal and panelhostoption iscontainer,LazyPanelHostisLazyPanelContainer, and the test helperharness()issetup().Retire the old host names and finish the rename:SyntheticHostisSyntheticMachine,HOSTED_OFFERisSERVED_OFFER, and database errors say "database". The retired-symbol scan gainsHostBackend,HostAccess,HostRoot,identity_to_host,inject_host,inject_host_with_var,install_host_apis,host_injectedandHostGlobal. The rootAGENTS.mdno longer says these names wait for a rename.Rename the remaining host names: one gateway deprecation message.What stays
Names and messages that already mean the Host stay:
HostSnapshot,set_host, "User input is unavailable in this host", and "this host provides none". Network and Cargo names (require_loopback_host,max_per_host,host_triple) stay as well.Verification
Commits 1 to 4:
description; no code file gains lines; the__impl_*.luapreludes keep their exact line counts (checked by script against the parent commit).cargo fmt --check, both clippy sets with-D warnings, the full nextest and doctest runs, workspace and facadecargo docwith-D warnings,cargo +nightly-2026-09-05 xtask api --check,cargo xtask site --books-only, and both npm suites all pass. The guard was shown to fail on a planted "production host" line.Commits 5 to 12:
promptforge.engine.store_phase).