System Run Cart

This commit is contained in:
2026-07-03 09:56:02 +01:00
parent 23d3ed641e
commit 2ab5c43334
7 changed files with 670 additions and 28 deletions
@@ -0,0 +1,90 @@
---
id: PLN-0129
ticket: system-run-cart
title: Remove Userland Run Cart ABI Surface
status: open
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` removes `system.run_cart` from the userland guest ABI. This plan
covers the public ABI, syscall registry/declaration surface, generated metadata,
and documentation/spec propagation. It does not change runtime dispatch behavior
or direct boot tests; those are covered by `PLN-0130` and `PLN-0131`.
## Objective
Remove `system.run_cart` from every app-callable/userland ABI surface while
preserving non-guest direct boot entrypoints.
## Dependencies
- Source decision: `DEC-0035`.
- Must stay scoped away from `AGD-0041` and `AGD-0044`.
- Coordinate with `PLN-0130` so runtime dispatch does not retain a callable
success path after the declaration is removed.
## Scope
- Remove or retire `Syscall::SystemRunCart` from userland-visible syscall
declarations in `crates/console/prometeu-hal/src/syscalls.rs`.
- Remove the `system.run_cart` registry entry from
`crates/console/prometeu-hal/src/syscalls/domains/system.rs` and
`crates/console/prometeu-hal/src/syscalls/registry.rs`, unless implementation
discovers an internal-only registry distinct from guest ABI.
- Remove generated/static bytecode or VM-facing declarations that expose
`system.run_cart`, including known references in
`crates/console/prometeu-bytecode/src/model.rs` and
`crates/console/prometeu-vm/src/virtual_machine.rs` if they include it.
- Update docs/specs that mention `system.run_cart` as app-callable.
- Update `AGD-0004` references only if they become factually misleading after
removal; do not close or reinterpret that agenda.
## Non-Goals
- Do not implement `Home -> another Game`.
- Do not add a replacement app navigation syscall.
- Do not implement `.pmc`.
- Do not change direct host/CLI/debug boot behavior.
- Do not add compatibility stubs for obsolete guest code.
## Execution Method
1. Search for `SystemRunCart`, `run_cart`, and `"system", "run_cart"` across
`crates/`, `docs/`, and `discussion/`.
2. Remove `system.run_cart` from userland syscall domain declarations and
lookup/name registries.
3. Remove generated/static guest-facing metadata entries that advertise
`system.run_cart`.
4. Update docs/specs to state that cartridges are booted by host/system paths,
not by guest syscall.
5. Compile the workspace or targeted crates to find stale references.
## Acceptance Criteria
- No userland ABI declaration advertises `system.run_cart`.
- No generated guest metadata exposes `run_cart` as callable.
- Documentation/spec text no longer describes app-callable cartridge boot.
- Any retained code path is clearly internal-only and is not reachable through
guest syscall lookup.
## Tests
- Add or update syscall registry tests to assert `system.run_cart` is absent
from the public/userland registry.
- Run targeted tests for `prometeu-hal`, `prometeu-bytecode`, and
`prometeu-vm` if available.
- Run repository validation commands used for syscall declaration consistency.
## Affected Artifacts
- `crates/console/prometeu-hal/src/syscalls.rs`
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
- `crates/console/prometeu-hal/src/syscalls/registry.rs`
- `crates/console/prometeu-bytecode/src/model.rs`
- `crates/console/prometeu-vm/src/virtual_machine.rs`
- `docs/specs/runtime/`
- `discussion/workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md`
@@ -0,0 +1,79 @@
---
id: PLN-0130
ticket: system-run-cart
title: Remove Runtime Run Cart Stub Dispatch
status: open
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` forbids a callable userland `system.run_cart` stub. This plan covers
runtime and VM dispatch cleanup so obsolete calls cannot silently succeed.
Public ABI removal is handled by `PLN-0129`; direct boot preservation is handled
by `PLN-0131`.
## Objective
Remove the runtime no-op dispatch path for `SystemRunCart` and ensure stale or
obsolete userland attempts fail explicitly rather than returning success.
## Dependencies
- Source decision: `DEC-0035`.
- Depends on the ABI direction in `PLN-0129`, but can be implemented in the same
PR if the public enum/registry removal and dispatch cleanup move together.
## Scope
- Remove the `Syscall::SystemRunCart => return Ok(())` path from
`crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
- Update any match arms made unreachable or obsolete by removing
`SystemRunCart`.
- Ensure stale numeric syscall ids or stale bytecode declarations fail with the
repository's existing unknown/invalid syscall behavior.
- Add negative coverage for userland attempts to invoke the removed operation,
using the closest existing VM runtime syscall tests.
## Non-Goals
- Do not implement a replacement navigation operation.
- Do not implement the `Home -> another Game` orchestrator.
- Do not alter direct host/CLI/debug cartridge boot paths.
- Do not change `system.has_cart` behavior unless required by compile fallout.
## Execution Method
1. Inspect `dispatch.rs` for all `SystemRunCart` match arms.
2. Remove the no-op success path and any unreachable arms tied only to
`SystemRunCart`.
3. If the public enum variant is removed by `PLN-0129`, update exhaustiveness
and registry mapping accordingly.
4. Add or update VM runtime tests that demonstrate `system.run_cart` is not
callable from guest/userland.
5. Run targeted runtime tests and compile checks.
## Acceptance Criteria
- There is no runtime path where a guest `system.run_cart` call returns `Ok(())`.
- Stale/obsolete attempts fail explicitly through existing invalid syscall or
declaration validation behavior.
- `system.has_cart` and unrelated system syscalls keep their current behavior.
- Runtime dispatch remains exhaustive and clear after removing `SystemRunCart`.
## Tests
- Add a negative test in `crates/console/prometeu-system/src/services/vm_runtime`
for stale userland `run_cart` attempts, if the test harness can express it.
- Run `cargo test` for `prometeu-system` and any impacted syscall crates.
- Run a workspace compile/test command if targeted tests reveal cross-crate enum
fallout.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
- `crates/console/prometeu-hal/src/syscalls.rs`
- `crates/console/prometeu-hal/src/syscalls/registry.rs`
@@ -0,0 +1,83 @@
---
id: PLN-0131
ticket: system-run-cart
title: Preserve Direct Cartridge Boot Coverage
status: open
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` removes userland `system.run_cart`, but direct cartridge boot remains
mandatory for development, debugging, automated tests, and future single-game
launch scenarios. This plan protects that path while the guest syscall is
removed.
## Objective
Preserve and test host/CLI/debug direct cartridge boot without relying on a
guest syscall.
## Dependencies
- Source decision: `DEC-0035`.
- Can be implemented after or alongside `PLN-0129` and `PLN-0130`.
- Must not depend on `.pmc`, app catalog, launcher UX, `AGD-0041`, or
`AGD-0044`.
## Scope
- Identify direct boot entrypoints in `crates/tools/prometeu-cli/src/main.rs`,
`crates/host/prometeu-host-desktop-winit/src/lib.rs`,
`crates/host/prometeu-host-desktop-winit/src/debugger.rs`, and firmware
cartridge loading code.
- Add or preserve tests showing a cartridge can be loaded directly into
firmware/runtime from host or CLI paths.
- Ensure these paths do not call or require `system.run_cart`.
- Document the distinction between direct boot and guest navigation where
runtime specs describe boot behavior.
## Non-Goals
- Do not implement `Home -> another Game`.
- Do not add app-callable navigation.
- Do not require `.pmc`.
- Do not redesign cartridge loader internals beyond what is required to keep
direct boot working.
## Execution Method
1. Trace the CLI/debug direct boot path from cartridge path argument through
loader, firmware `load_cartridge`, and runtime initialization.
2. Add regression tests at the lowest practical layer proving direct boot still
reaches `GameRunning` for a valid game cartridge.
3. Add a guard or assertion that direct boot does not depend on `system.run_cart`
metadata.
4. Update docs/specs to describe direct boot as host/system-controlled.
5. Run targeted CLI/firmware/host tests.
## Acceptance Criteria
- A valid game cartridge can still boot directly from host/CLI/debug paths.
- Direct boot does not depend on `system.run_cart` being in the guest syscall
registry.
- Existing debugger/handshake metadata that reports cartridge info still works.
- The direct boot behavior is documented as host/system entry, not guest ABI.
## Tests
- Add or preserve firmware tests around `load_cartridge` and `GameRunning`.
- Add or preserve host/CLI tests for cartridge path boot when practical.
- Run `cargo test` for `prometeu-firmware`, `prometeu-host-desktop-winit`, and
`prometeu-cli` where available.
## Affected Artifacts
- `crates/tools/prometeu-cli/src/main.rs`
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `docs/specs/runtime/`