From aaf4dff69d5eae3ceab73e163ae4bcae21845596 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sun, 19 Apr 2026 08:37:21 +0100 Subject: [PATCH] [PERF] Runtime Introspection Syscalls --- discussion/index.ndjson | 4 +- ...0009-host-owned-debug-and-certification.md | 11 +-- ...PLN-0030-dec9-spec-boundary-propagation.md | 86 +++++++++++++++++++ .../PLN-0031-dec9-runtime-bank-abi-cleanup.md | 85 ++++++++++++++++++ ...st-debugger-and-certification-alignment.md | 84 ++++++++++++++++++ .../runtime/09-events-and-concurrency.md | 2 +- .../10-debug-inspection-and-profiling.md | 77 +++++++++-------- ...ortability-and-cross-platform-execution.md | 2 +- docs/specs/runtime/15-asset-management.md | 57 ++++++------ .../specs/runtime/16-host-abi-and-syscalls.md | 11 +++ docs/specs/runtime/16a-syscall-policies.md | 13 ++- 11 files changed, 361 insertions(+), 71 deletions(-) create mode 100644 discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md create mode 100644 discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md create mode 100644 discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index c059777b..ff3c5058 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":30,"LSN":34,"CLSN":1}} +{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":33,"LSN":34,"CLSN":1}} {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} {"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} @@ -14,7 +14,7 @@ {"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0012","status":"review","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-18","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0009","file":"workflow/decisions/DEC-0009-host-owned-debug-and-certification.md","status":"review","created_at":"2026-04-18","updated_at":"2026-04-18","ref_agenda":"AGD-0011"}],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0012","status":"review","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0009","file":"workflow/decisions/DEC-0009-host-owned-debug-and-certification.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-19","ref_agenda":"AGD-0011"}],"plans":[{"id":"PLN-0030","file":"workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0031","file":"workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md","status":"review","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0032","file":"workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md","status":"review","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]}],"lessons":[]} {"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]} diff --git a/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md b/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md index a76688e6..d1371936 100644 --- a/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md +++ b/discussion/workflow/decisions/DEC-0009-host-owned-debug-and-certification.md @@ -2,19 +2,19 @@ id: DEC-0009 ticket: perf-runtime-introspection-syscalls title: Host-Owned Debug and Certification -status: review +status: accepted created: 2026-04-18 -accepted: +accepted: 2026-04-19 agenda: AGD-0011 -plans: [] +plans: [PLN-0030, PLN-0031, PLN-0032] tags: [perf, runtime, host, debug, certification, syscall, telemetry] --- ## Status -Review +Accepted -Normative draft derived from `AGD-0011`. It is intended to lock the boundary between runtime operational surface and host-owned development tooling. +Accepted normative decision derived from `AGD-0011`. It locks the boundary between runtime operational surface and host-owned development tooling. ## Contexto @@ -96,3 +96,4 @@ The decision also aligns the runtime with prior convergence already visible in t ## Revision Log - 2026-04-18: Initial draft from AGD-0011. +- 2026-04-19: Accepted and decomposed into `PLN-0030`, `PLN-0031`, and `PLN-0032`. diff --git a/discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md b/discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md new file mode 100644 index 00000000..68cba3ef --- /dev/null +++ b/discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md @@ -0,0 +1,86 @@ +--- +id: PLN-0030 +ticket: perf-runtime-introspection-syscalls +title: DEC-0009 Spec Boundary Propagation +status: done +created: 2026-04-19 +completed: 2026-04-19 +tags: [runtime, spec, host, debug, certification, syscall] +--- + +## Briefing + +Propagate `DEC-0009` into the canonical runtime specifications so that debug tooling and certification are described as host-owned concerns, not guest/runtime feature surfaces. + +## Decisions de Origem + +- `DEC-0009` - Host-Owned Debug and Certification + +## Alvo + +Lock the written contract across the runtime specs before code execution starts, so implementation work does not reopen the architecture. + +## Escopo + +- update `docs/specs/runtime/10-debug-inspection-and-profiling.md` to narrow the runtime-visible diagnostics surface and state explicitly that detailed inspection and certification output are host-owned; +- update `docs/specs/runtime/15-asset-management.md` to keep bank telemetry slot-first and prohibit guest-visible debug-oriented bank inspection as a general ABI; +- update `docs/specs/runtime/16-host-abi-and-syscalls.md` so `bank.info` / `bank.slot_info` are either removed from the public syscall catalog or redefined only as bounded operational ABI; +- update `docs/specs/runtime/16a-syscall-policies.md` to reinforce that debug convenience APIs are not valid justification for guest-visible syscalls; +- align cross-references to existing host-overlay and telemetry chapters where they already define the canonical diagnostics pipeline. + +## Fora de Escopo + +- changing Rust code in `crates/`; +- introducing a new guest-facing inspection ABI; +- redesigning debugger transport or host protocol payload schemas. + +## Plano de Execucao + +### Step 1 - Rewrite the normative ownership language + +**What:** Rewrite the affected spec chapters so that debug tooling, rich inspection, and certification reporting are host-owned responsibilities. +**How:** Replace guest/runtime-centric wording in `10-debug-inspection-and-profiling.md` with host-owned framing, keeping runtime obligations limited to bounded telemetry production and deterministic machine behavior. +**File(s):** `docs/specs/runtime/10-debug-inspection-and-profiling.md` + +### Step 2 - Converge the asset/bank contract + +**What:** Align asset-management language with the decision that slot-first telemetry is the visible contract and bank inspection is not a general guest debug service. +**How:** Update the bank telemetry and diagnostics sections to describe the canonical operational summary, the absence of JSON textual bank ABI, and the host ownership of detailed slot inspection. +**File(s):** `docs/specs/runtime/15-asset-management.md` + +### Step 3 - Tighten the syscall chapter + +**What:** Remove ambiguity around `bank.info` and `bank.slot_info` in the public ABI contract. +**How:** Amend the host ABI and syscall policy chapters so they either remove those calls from the public surface or constrain any surviving `bank.info` form to a cheap, deterministic, non-JSON operational summary justified by machine needs. +**File(s):** `docs/specs/runtime/16-host-abi-and-syscalls.md`, `docs/specs/runtime/16a-syscall-policies.md` + +### Step 4 - Verify cross-chapter consistency + +**What:** Ensure no remaining chapter describes certification or debug tooling as runtime-owned functionality. +**How:** Review cross-references in nearby runtime chapters that mention certification, host tooling, or diagnostics and patch inconsistent wording where directly impacted by the edited contract. +**File(s):** `docs/specs/runtime/09-events-and-concurrency.md`, `docs/specs/runtime/11-portability-and-cross-platform-execution.md`, plus the edited primary chapters + +## Criterios de Aceite + +- `DEC-0009` is cited explicitly in the updated spec material. +- The specs state unambiguously that certification generation is host-owned. +- The specs no longer describe JSON-formatted bank inspection as part of the long-term public guest ABI. +- The public runtime contract for bank telemetry remains slot-first and bounded. +- The updated text is internally consistent across the touched runtime chapters. + +## Tests / Validacao + +- manual doc review of the edited chapters for contradictory wording about ownership; +- targeted search for `bank.info`, `bank.slot_info`, `certification`, and `debug` in `docs/specs/runtime/` to ensure the remaining text matches `DEC-0009`; +- verify that all new or changed published spec text remains in English. + +## Riscos + +- spec-only propagation may accidentally leave residual guest-oriented language that later reintroduces ABI ambiguity; +- over-editing adjacent chapters could broaden the scope beyond `DEC-0009`; +- under-specifying the surviving `bank.info` option could block the runtime ABI cleanup plan. + +## Dependencies + +- `DEC-0009` must remain accepted and unchanged while this plan is executed. +- This plan should complete before runtime syscall removal or narrowing work begins. diff --git a/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md b/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md new file mode 100644 index 00000000..101254fd --- /dev/null +++ b/discussion/workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md @@ -0,0 +1,85 @@ +--- +id: PLN-0031 +ticket: perf-runtime-introspection-syscalls +title: DEC-0009 Runtime Bank ABI Cleanup +status: review +created: 2026-04-19 +completed: +tags: [runtime, syscall, abi, bank, telemetry, debug] +--- + +## Briefing + +Execute the runtime-side ABI cleanup mandated by `DEC-0009` by removing or narrowing guest-visible bank inspection syscalls and eliminating JSON formatting from dispatch. + +## Decisions de Origem + +- `DEC-0009` - Host-Owned Debug and Certification + +## Alvo + +Bring the public runtime syscall surface into compliance with the accepted decision while preserving any truly necessary cheap operational summary. + +## Escopo + +- review and update the public bank syscall registry in `crates/console/prometeu-hal/src/syscalls/domains/bank.rs`; +- refactor bank syscall dispatch in `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`; +- align runtime tests around the new ABI shape and the removal of JSON string payloads; +- keep internal asset telemetry and `slot_info` helpers available for host/runtime internals where they are still needed. + +## Fora de Escopo + +- changing the desktop debugger protocol payloads; +- introducing a new host transport; +- modifying unrelated asset loading semantics or slot ownership rules. + +## Plano de Execucao + +### Step 1 - Decide the surviving machine-facing bank surface + +**What:** Resolve the exact runtime-facing outcome for `bank.info` and `bank.slot_info` under the accepted decision. +**How:** Use the accepted spec text from `PLN-0030` as the source of truth and implement one of two bounded outcomes: remove both public syscalls, or keep only a cheap non-JSON `bank.info` summary if an operational use case remains documented. +**File(s):** `docs/specs/runtime/16-host-abi-and-syscalls.md`, `crates/console/prometeu-hal/src/syscalls/domains/bank.rs` + +### Step 2 - Remove JSON-on-the-wire dispatch behavior + +**What:** Eliminate textual JSON serialization from the runtime dispatch path. +**How:** Delete the `serde_json::to_string` bank inspection branches in `virtual_machine_runtime/dispatch.rs` and replace them with the chosen bounded ABI behavior from Step 1. +**File(s):** `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs` + +### Step 3 - Realign tests and syscall metadata + +**What:** Update test coverage and metadata assumptions to the new bank syscall contract. +**How:** Add or update tests for registry shape, return-slot behavior, and fault/status behavior so the runtime proves that debug-only bank inspection no longer leaks through the guest ABI. +**File(s):** `crates/console/prometeu-hal/src/syscalls/domains/bank.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`, any syscall metadata tests discovered during execution + +### Step 4 - Preserve internal host-facing inspection sources + +**What:** Keep slot and bank telemetry available for host-owned tooling without re-exporting them as guest ABI. +**How:** Verify that `AssetManager` telemetry helpers and internal `slot_info` access remain usable by host/runtime internals after the public syscall cleanup. +**File(s):** `crates/console/prometeu-drivers/src/asset.rs`, related internal callers discovered during execution + +## Criterios de Aceite + +- The public bank syscall registry no longer exposes JSON-formatted debug inspection. +- `virtual_machine_runtime/dispatch.rs` no longer serializes bank telemetry or slot details into JSON strings for guest return values. +- Any surviving `bank.info` surface is cheap, deterministic, bounded, and documented as operational ABI. +- Guest code cannot access detailed slot inspection through a generic debug convenience syscall. +- Runtime tests cover the new ABI behavior. + +## Tests / Validacao + +- unit tests for syscall registry metadata and runtime dispatch behavior; +- targeted search for `serde_json::to_string`, `BankInfo`, and `BankSlotInfo` in the runtime crates after the refactor; +- run the affected Rust test suites for HAL/system crates that cover syscall dispatch and bank telemetry behavior. + +## Riscos + +- removing syscalls without finishing spec propagation first may create contract drift; +- keeping a reduced `bank.info` without a crisp return shape may preserve ambiguity; +- internal host tooling might still rely on code paths that currently sit behind the guest syscall implementation. + +## Dependencies + +- `PLN-0030` should land first or in lockstep so the code change follows published contract text. +- Host tooling migration work in `PLN-0032` may depend on internal inspection helpers preserved by this plan. diff --git a/discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md b/discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md new file mode 100644 index 00000000..f53ef6b7 --- /dev/null +++ b/discussion/workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md @@ -0,0 +1,84 @@ +--- +id: PLN-0032 +ticket: perf-runtime-introspection-syscalls +title: DEC-0009 Host Debugger and Certification Alignment +status: review +created: 2026-04-19 +completed: +tags: [host, debug, certification, telemetry, desktop] +--- + +## Briefing + +Align the desktop host debugger and certification pipeline with `DEC-0009` so detailed inspection and certification outputs are consumed from host-owned telemetry/debug flows rather than from guest-visible runtime APIs. + +## Decisions de Origem + +- `DEC-0009` - Host-Owned Debug and Certification + +## Alvo + +Make the desktop host the canonical consumer of runtime telemetry, certification configuration, and detailed inspection data after the guest ABI cleanup. + +## Escopo + +- review `crates/host/prometeu-host-desktop-winit/src/debugger.rs` for reliance on guest-facing inspection assumptions and document the intended host-owned data sources; +- review `crates/host/prometeu-host-desktop-winit/src/cap.rs` and certification wiring in `runner.rs` so certification remains fully host-generated; +- align any host-side contracts with the accepted spec and runtime ABI cleanup; +- add or update tests that prove certification/debug behavior does not depend on guest-visible debug syscalls. + +## Fora de Escopo + +- redesigning the external debugger client application; +- changing unrelated desktop rendering or overlay presentation behavior; +- adding new certification metrics beyond what existing telemetry already supports. + +## Plano de Execucao + +### Step 1 - Audit host data sources + +**What:** Identify where the desktop host already consumes telemetry and where it still implicitly depends on guest-oriented inspection concepts. +**How:** Review `debugger.rs`, `runner.rs`, and supporting modules for state, telemetry, certification, and inspection flows; record which inputs come from atomic telemetry, crash reports, or direct host/runtime internals. +**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `crates/host/prometeu-host-desktop-winit/src/overlay.rs` + +### Step 2 - Lock certification ownership in host code + +**What:** Ensure certification remains generated and configured exclusively in the host layer. +**How:** Update certification setup and any related documentation/comments so host code owns report generation and consumes runtime telemetry snapshots rather than guest-facing diagnostic APIs. +**File(s):** `crates/host/prometeu-host-desktop-winit/src/cap.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs` + +### Step 3 - Adjust debugger integration after ABI cleanup + +**What:** Keep rich inspection available to developer tooling after `PLN-0031` removes or narrows guest bank inspection syscalls. +**How:** Move any remaining detailed inspection dependence onto host-owned runtime access paths or protocol messages that do not reintroduce guest ABI surface. +**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, related protocol or host integration files discovered during execution + +### Step 4 - Prove the boundary in tests + +**What:** Add evidence that host tooling and certification still work without guest-visible debug syscalls. +**How:** Extend host tests around debugger startup, telemetry streaming, and certification config loading, and add focused assertions that the host path depends on telemetry/internal access rather than guest ABI inspection. +**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`, `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `crates/host/prometeu-host-desktop-winit/src/cap.rs` + +## Criterios de Aceite + +- The host debugger and certification pipeline are described and implemented as host-owned consumers. +- No host feature requires `bank.slot_info` or JSON `bank.info` to remain exposed to guest code. +- Certification configuration and report generation stay in host code. +- Host-side tests cover the intended telemetry/debug/certification path after ABI cleanup. + +## Tests / Validacao + +- run host crate tests covering debugger startup, command handling, and certification config loading; +- targeted search in the host crate for references to guest-visible bank inspection APIs after implementation; +- manual review that host comments and module responsibilities match `DEC-0009`. + +## Riscos + +- host code may still rely on implicit runtime internals that are not clearly documented; +- coupling host tooling migration to runtime ABI cleanup could stall both if sequencing is unclear; +- lack of explicit host-side test coverage may hide regressions until manual debugger use. + +## Dependencies + +- `PLN-0030` provides the published ownership model. +- `PLN-0031` defines the final runtime ABI boundary that host tooling must stop depending on. diff --git a/docs/specs/runtime/09-events-and-concurrency.md b/docs/specs/runtime/09-events-and-concurrency.md index bfba647f..200ad704 100644 --- a/docs/specs/runtime/09-events-and-concurrency.md +++ b/docs/specs/runtime/09-events-and-concurrency.md @@ -98,7 +98,7 @@ Important properties: - events are processed at known points; - no execution occurs outside the frame loop; -- frame structure remains observable for tooling and certification. +- frame structure remains observable for host tooling and host-owned certification. ## 7 Determinism and Best Practices diff --git a/docs/specs/runtime/10-debug-inspection-and-profiling.md b/docs/specs/runtime/10-debug-inspection-and-profiling.md index 50db8446..4f140f23 100644 --- a/docs/specs/runtime/10-debug-inspection-and-profiling.md +++ b/docs/specs/runtime/10-debug-inspection-and-profiling.md @@ -7,19 +7,18 @@ Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../ ## 1 Scope -This chapter defines the machine-visible debugging, inspection, and profiling surface of PROMETEU. +This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU after `DEC-0009`. + +`DEC-0009` locks debug tooling and certification output as host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface. It covers: -- execution modes; -- pause and stepping; -- state inspection; -- graphics inspection; +- runtime-visible execution control used by host tooling; +- bounded operational telemetry; - profiling; -- breakpoints and watchpoints; - event and fault visibility; -- certification-facing diagnostics; -- Host-side debug overlay (HUD) isolation. +- certification input data; +- host-side debug overlay (HUD) isolation. ## 2 Execution Modes @@ -34,18 +33,18 @@ PROMETEU operates in three main modes: ### 2.2 Debug Mode - controlled execution -- access to internal state +- host-mediated access to internal state - pauses and stepping ### 2.3 Certification Mode - deterministic execution - collected metrics -- report generation +- host-generated report output No mode alters the logical result of the program. -## 3 Execution Debug +## 3 Execution Control ### 3.1 Pause and Resume @@ -64,24 +63,26 @@ During pause: ### 3.2 Step-by-Step -PROMETEU allows stepping at different levels: +PROMETEU allows host tooling to step execution at different levels: - **by frame** - **by function** - **by VM instruction** -Stepping by instruction reveals: +When the host activates instruction-level inspection, it may observe: - Program Counter (PC) - current instruction - operand stack - call stack -## 4 State Inspection +## 4 State Inspection Boundary + +Detailed state inspection is a host-owned concern. The runtime may expose deterministic machine state to host tooling, but this chapter does not define a general guest ABI for introspection convenience. ### 4.1 Stacks -PROMETEU allows inspecting: +Host tooling may inspect: - **Operand Stack** - **Call Stack** @@ -94,7 +95,7 @@ For each frame: ### 4.2 Heap -The heap can be inspected in real time: +The host may inspect heap state in real time: - total size - current usage @@ -109,22 +110,22 @@ The programmer can observe: ### 4.3 Global Space -Global variables: +Host-owned inspection may observe global variables, including: - current values - references - initialization -## 5 Graphics Debug +## 5 Graphics Inspection Boundary -PROMETEU allows inspecting the graphics system: +Host tooling may inspect the graphics system: - front buffer - back buffer - palette state - active sprites -It is possible to: +The host may: - freeze the image - observe buffers separately @@ -153,7 +154,7 @@ SYSTEM:612 ### 6.2 Per-Function Profiling -PROMETEU can associate cycles with: +Host tooling may associate cycles with: - functions - methods @@ -161,7 +162,7 @@ PROMETEU can associate cycles with: ### 6.3 Per-Instruction Profiling -At the lowest level, the system can display: +At the lowest level, host tooling can display: - executed instructions - individual cost @@ -185,13 +186,13 @@ Peak:34KB❌ Limit:32KB ``` -These data directly feed the certification. +These data feed host-owned certification. ### 7.1 Bank Occupancy Profiling Bank occupancy diagnostics are slot-first. -The visible per-bank telemetry used by host inspection surfaces and certification is: +The visible per-bank telemetry used by host inspection surfaces and host-owned certification is: - `bank_type` - `used_slots` @@ -206,9 +207,11 @@ Byte-oriented bank occupancy is not the canonical visible profiling contract. ## 8 Breakpoints and Watchpoints +Breakpoints and watchpoints are host-mediated tooling controls. They are not part of the gameplay-facing cartridge contract. + ### 8.1 Breakpoints -PROMETEU supports breakpoints in: +The platform supports host-owned breakpoints in: - specific frames - functions @@ -222,7 +225,7 @@ Breakpoints: ### 8.2 Watchpoints -Watchpoints monitor: +Host tooling may monitor watchpoints over: - variables - heap addresses @@ -233,10 +236,14 @@ Execution can pause when: - a value changes - a limit is exceeded -## 9 Event and Fault Debugging +## 9 Event and Fault Diagnostics ## 10 Certification Diagnostics +Certification diagnostics are produced by the host from deterministic runtime telemetry. + +The runtime does not generate the final certification artifact. It only maintains the machine-facing counters and summaries required for host-owned certification. + Certification diagnostics may enforce bank occupancy ceilings. For bank residency, certification uses slot-based limits, such as: @@ -246,7 +253,7 @@ For bank residency, certification uses slot-based limits, such as: Bank certification MUST NOT depend on `max_gfx_bytes` or `max_audio_bytes`. -PROMETEU allows observing: +Host tooling may observe: - event queue - active timers @@ -259,7 +266,7 @@ Each event has: - cost - consequence -## 10 Host-Side Debug Overlay (HUD) Isolation +## 11 Host-Side Debug Overlay (HUD) Isolation The visual Debug Overlay (HUD) for technical inspection is not part of the emulated machine pipeline. @@ -270,7 +277,7 @@ The visual Debug Overlay (HUD) for technical inspection is not part of the emula 3. **Host overlay module:** The Desktop Host owns a dedicated overlay module that performs host-side text, panel, and simple bar composition. 4. **Composition boundary:** The overlay is composed on the Host presentation surface after the emulated frame is ready. Overlay pixels must not be written back into the emulated framebuffer. 5. **Host control:** Overlay visibility and presentation policy remain under Host control. -2. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer. +6. **Host (Desktop):** Responsible for collecting telemetry from the runtime and rendering the HUD as a native, transparent layer. ### 10.2 Principles @@ -287,11 +294,11 @@ To ensure zero-impact synchronization between the VM and the Host Debug Overlay, 3. **Single Source of Truth:** This model is the exclusive source of truth for both real-time inspection and frame-end certification, replacing legacy per-frame buffered fields. 4. **Frame-Closed Log Metric:** `logs_count` in the snapshot represents the number of logs emitted in the last completed logical frame, not a transient in-flight counter. -## 11 Integration with CAP and Certification +## 12 Integration with CAP and Certification -All debug and profiling data: +All machine diagnostics and profiling data: -- feed the certification report -- are collected deterministically -- do not depend on external tools +- feed the host-owned certification report; +- are collected deterministically; +- do not require a guest-visible debug ABI; - are consistent regardless of whether the Host HUD is active or not. diff --git a/docs/specs/runtime/11-portability-and-cross-platform-execution.md b/docs/specs/runtime/11-portability-and-cross-platform-execution.md index e745eef9..dac986f4 100644 --- a/docs/specs/runtime/11-portability-and-cross-platform-execution.md +++ b/docs/specs/runtime/11-portability-and-cross-platform-execution.md @@ -162,7 +162,7 @@ Without changing semantics. ## 11 Certification and Portability -The **PROMETEU Certification** is valid for all platforms. +The host-owned **PROMETEU Certification** is valid for all platforms. If a cartridge: diff --git a/docs/specs/runtime/15-asset-management.md b/docs/specs/runtime/15-asset-management.md index 90c56683..9de63331 100644 --- a/docs/specs/runtime/15-asset-management.md +++ b/docs/specs/runtime/15-asset-management.md @@ -110,44 +110,44 @@ This table describes content identity and storage layout, not live residency. ### 4.1 `TILES` asset contract in v1 -Para `BankType::TILES`, o contrato v1 voltado para o runtime é: +For `BankType::TILES`, the v1 runtime-facing contract is: - `codec = NONE` -- pixels serializados usam índices de paleta `u4` empacotados -- paletas serializadas usam `RGB565` (`u16`, little-endian) +- serialized pixels use packed `u4` palette indices +- serialized palettes use `RGB565` (`u16`, little-endian) - `palette_count = 64` -- a materialização em runtime pode expandir índices de pixel para um `u8` por pixel +- runtime materialization may expand pixel indices to one `u8` per pixel -`NONE` para `TILES` significa que não há camada de codec genérica adicional além do próprio contrato do banco. +For `TILES`, `NONE` means there is no additional generic codec layer beyond the bank contract itself. -Para a janela de transição atual: +For the current transition window: -- `RAW` é um alias legado e depreciado de `NONE` -- novos materiais publicados devem usar `NONE` como valor canônico +- `RAW` is a legacy deprecated alias of `NONE` +- newly published material must use `NONE` as the canonical value -Mesmo com `codec = NONE`, `TILES` ainda requer decode específico de banco a partir de seu payload serializado. O layout de bytes serializados não precisa, portanto, ser idêntico ao layout em memória. +Even with `codec = NONE`, `TILES` still requires bank-specific decode from its serialized payload. The serialized byte layout therefore does not need to match the in-memory layout. #### 4.1.1 Metadata Normalization -Seguindo a `DEC-0004`, o campo `AssetEntry.metadata` deve ser estruturado de forma segmentada para evitar ambiguidades. +Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity. -Campos de metadados obrigatórios (efetivos) para `TILES` no nível raiz: +Required effective metadata fields for `TILES` at the root level: -- `tile_size`: aresta do tile em pixels; valores válidos são `8`, `16`, ou `32` -- `width`: largura total da folha do banco em pixels -- `height`: altura total da folha do banco em pixels -- `palette_count`: número de paletas serializadas para o banco +- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32` +- `width`: total sheet width in pixels +- `height`: total sheet height in pixels +- `palette_count`: number of serialized palettes for the bank -Subárvores opcionais e informativas: +Optional informative subtrees: -- `metadata.codec`: Configuração específica do codec/compressor (ex: dicionários, flags de compressão). -- `metadata.pipeline`: Metadados informativos do processo de build do Studio (ex: source hashes, timestamps, tool versions). +- `metadata.codec`: codec/compressor-specific configuration (for example dictionaries or compression flags). +- `metadata.pipeline`: informative metadata from the Studio build process (for example source hashes, timestamps, or tool versions). -Regras de validação para `TILES` v1: +Validation rules for `TILES` v1: -- `palette_count` deve ser `64` -- `width * height` define o número de pixels indexados lógicos na folha decodificada -- metadados adicionais podem existir, mas o contrato do runtime não deve depender deles para reconstruir o banco em memória (exceto se definidos na raiz como campos efetivos). +- `palette_count` must be `64` +- `width * height` defines the number of logical indexed pixels in the decoded sheet +- extra metadata may exist, but the runtime contract must not depend on it to reconstruct the in-memory bank unless that data is defined at the root as an effective field. #### 4.1.2 Payload Layout @@ -202,7 +202,8 @@ Rules: - the visible contract MUST NOT expose byte-oriented bank occupancy as the canonical summary; - canonical bank names are `GLYPH` and `SOUNDS`; -- detailed occupancy inspection remains slot-based through slot references, not bank byte totals; +- detailed occupancy inspection remains host-owned and slot-based through slot references, not bank byte totals; +- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI after `DEC-0009`; - any residual byte accounting MAY exist internally, but it is not part of the visible bank telemetry contract. ## 6 Load Lifecycle @@ -255,9 +256,9 @@ Therefore: - shutting down a cartridge can release bank residency independently of VM heap behavior. - the runtime must not keep the full `assets.pa` payload resident in RAM as a baseline requirement. -## 8 Bank Telemetry +## 8 Bank Telemetry and Inspection Boundary -The runtime surfaces bank and slot statistics such as: +The runtime may maintain bank and slot statistics such as: - total bytes; - used bytes; @@ -266,7 +267,11 @@ The runtime surfaces bank and slot statistics such as: - slot occupancy; - resident asset identity per slot. -These metrics support debugging, telemetry, and certification-oriented inspection. +These metrics support host-owned debugging, telemetry, and certification-oriented inspection. + +Only bounded operational summaries belong to the public runtime contract. + +Detailed per-slot inspection is valid for host tooling and runtime internals, but it must not be treated as a general guest-visible debug convenience API. ## 9 Preload diff --git a/docs/specs/runtime/16-host-abi-and-syscalls.md b/docs/specs/runtime/16-host-abi-and-syscalls.md index 0e2b4c1b..85467369 100644 --- a/docs/specs/runtime/16-host-abi-and-syscalls.md +++ b/docs/specs/runtime/16-host-abi-and-syscalls.md @@ -15,6 +15,8 @@ It focuses on: Operational policies such as capabilities, fault classes, determinism, GC interaction, budgeting, and blocking are split into a companion chapter. +Per `DEC-0009`, debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI. + ## 1 Design Principles The syscall ABI follows these rules: @@ -199,6 +201,15 @@ For `asset.load`: - `slot` is the target slot index; - bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller. +### Bank diagnostics surface (`bank`, v1) + +`DEC-0009` narrows the public bank contract: + +- `bank.slot_info` is host/debug tooling surface and is not part of the canonical long-term guest ABI; +- JSON-on-the-wire bank inspection payloads are not valid public ABI; +- if a public `bank.info` surface survives implementation cleanup, it must be reduced to a cheap deterministic operational summary aligned with the slot-first bank telemetry contract from [`15-asset-management.md`](15-asset-management.md); +- if no machine-facing operational need remains, `bank.info` should also be removed from the public guest ABI. + ### Composition surface (`composer`, v1) The canonical frame-orchestration public ABI uses module `composer`. diff --git a/docs/specs/runtime/16a-syscall-policies.md b/docs/specs/runtime/16a-syscall-policies.md index fb940b1f..1efb10ef 100644 --- a/docs/specs/runtime/16a-syscall-policies.md +++ b/docs/specs/runtime/16a-syscall-policies.md @@ -9,6 +9,8 @@ It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), whi Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1. +Per `DEC-0009`, guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling. + ## 1 Error Model: Faults vs Status Returns Syscalls use a status-first hybrid model. @@ -61,6 +63,7 @@ Practical rule: - `void` is allowed only for operations whose non-fault path is effectively unconditional success; - any operation with a meaningful operational non-success outcome must surface that outcome through `status`, not through absence of return values. +- debug-only or certification-only convenience calls are not justified public ABI even if they could be given a valid return shape. ### No-op policy @@ -77,6 +80,14 @@ This means operational problems must not be reclassified as: - `Trap`, when the failure is not structural; - `Panic`, when the failure is not an internal invariant break. +### Diagnostics boundary + +These policy constraints also apply to observability surfaces: + +- host-owned inspection and certification consumers may use runtime telemetry and internal host/runtime integration paths; +- guest-visible syscalls must be justified by machine-facing operational needs, not by tooling convenience; +- textual JSON diagnostics are not valid long-term public syscall ABI. + ## 2 Capability System Each syscall requires a declared capability. @@ -141,7 +152,7 @@ The system may account for: - cycles spent in syscalls; - allocations triggered by syscalls. -This keeps host interaction visible in certification, telemetry, and profiling. +This keeps host interaction visible in host-owned certification, telemetry, and profiling. ## 6 Blocking and Long Operations