System Run Cart
This commit is contained in:
@@ -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/`
|
||||
Reference in New Issue
Block a user