87 lines
4.8 KiB
Markdown
87 lines
4.8 KiB
Markdown
---
|
|
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.
|