prometeu-runtime/discussion/workflow/plans/PLN-0085-pbs-stdlib-and-syscall-declarations.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0085	render-frame-packet-boundary	PBS Stdlib and Syscall Declarations	done	2026-05-25	DEC-0030	gfx renderer runtime frame-composer architecture ui pipeline

Briefing

Source decision: DEC-0030.

Update PBS Game and Shell stdlibs so high-level APIs map to app-mode-specific ABI domains: Game uses composer.* and gfx2d.*; Shell uses gfxui.*.

Target

PBS authors can keep ergonomic high-level APIs where appropriate, but generated or declared syscalls use the correct DEC-0030 ABI domain for the active app mode.

Scope

• Update Game stdlib declarations for composer.* and gfx2d.*.
• Update Shell stdlib declarations for gfxui.*.
• Remove old primitive gfx.* ABI declarations.
• Keep author-facing wrappers clear about mode-specific behavior.
• Update examples/tests that compile PBS code.

Out of Scope

• Runtime implementation of the syscall handlers.
• New visual APIs beyond the domain split.
• Backward compatibility for old primitive gfx.* ABI declarations.
• Widget/layout redesign.

Execution Sequence

1. Inventory PBS stdlib files and syscall declaration generation.
2. Map Game scene/camera/sprites/HUD APIs to composer.*.
3. Map Game primitive APIs to gfx2d.*.
4. Map Shell primitive APIs to gfxui.*.
5. Remove or fail old primitive gfx.* ABI declarations.
6. Update PBS compile tests, examples, and syscall metadata expectations.

Acceptance Criteria

• PBS Game code emits only Game-allowed render ABI domains.
• PBS Shell code emits only Shell-allowed render ABI domains.
• Old primitive gfx.* ABI declarations are gone or explicitly rejected.
• Existing examples are updated to the new declarations.

Tests / Validation

• Run PBS stdlib and compiler tests.
• Add Game and Shell declaration tests for emitted syscall names.
• Add negative tests for wrong-domain declarations.

Risks

• User-facing API names may remain similar while ABI names change; tests must assert emitted syscall domains, not just wrapper names.
• Examples can mask stale declarations if they do not compile in both Game and Shell contexts.

Affected Artifacts

• PBS stdlib files
• Syscall declaration generation
• PBS tests and examples