prometeu-runtime/discussion/workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md

id	ticket	title	status	created	completed	tags
PLN-0030	perf-runtime-introspection-syscalls	DEC-0009 Spec Boundary Propagation	done	2026-04-19	2026-04-19	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.