prometeu-studio/docs/specs/pbs/15. Bytecode and PBX Mapping Specification.md

PBS Bytecode and PBX Mapping Specification

Status: Draft v0 (Skeleton)
Applies to: mapping from lowered PBS programs into PBX sections, bytecode-facing artifacts, and related source-to-artifact invariants

1. Purpose

This document will define the normative mapping between lowered PBS semantics and emitted PBX/bytecode-facing artifacts.

2. Scope

This document is intended to define:

• artifact-level obligations after lowering,
• mapping of semantic constructs into PBX-visible structures,
• source-to-artifact invariants required by verifier and loader stages,
• interaction points with host-binding metadata such as SYSC,
• interaction points with VM-owned builtin and intrinsic metadata.

This document does not define:

• the full bytecode ISA,
• UI/tooling presentation,
• one compiler's internal IR representation.

3. Authority and Precedence

Normative precedence:

1. Runtime authority (docs/specs/hardware/topics/chapter-2.md, chapter-3.md, chapter-9.md, chapter-12.md, chapter-16.md)
2. Bytecode authority (docs/specs/bytecode/ISA_CORE.md)
3. 6.1. Intrinsics and Builtin Types Specification.md
4. 6.2. Host ABI Binding and Loader Resolution Specification.md
5. 12. IR and Lowering Specification.md
6. This document

If a rule here conflicts with higher-precedence authorities, it is invalid.

4. Normative Inputs

This document depends on, at minimum:

• 6.1. Intrinsics and Builtin Types Specification.md
• 6.2. Host ABI Binding and Loader Resolution Specification.md
• 12. IR and Lowering Specification.md

5. Already-Settled Inputs

The following inputs are already fixed elsewhere and must not be contradicted here:

• The compiler emits host-binding declarations into PBX SYSC.
• Host-backed callsites are emitted in pre-load form as HOSTCALL <sysc_index>.
• SYSC entries are deduplicated by canonical identity and ordered by first occurrence.
• The loader resolves host bindings and rewrites HOSTCALL into SYSCALL.
• VM-owned builtin projections, builtin constants, and intrinsic callsites do not emit host-binding metadata.
• VM-owned intrinsic artifacts are distinct from SYSC, HOSTCALL, and SYSCALL.

6. Initial Section Targets

At minimum, the completed document should contain normative sections for:

1. artifact mapping goals,
2. section-level invariants,
3. callsite and control-flow mapping invariants,
4. metadata mapping obligations,
5. intrinsic and builtin artifact obligations,
6. source-attribution hooks for diagnostics/conformance.

7. A Ver

The following items remain to be closed in future agenda discussion.

• Which PBX sections beyond SYSC are part of the PBS-facing contract.
• Whether a distinct intrinsic declaration section is part of the PBS-facing contract in v1.
• Which source-level constructs require dedicated artifact patterns versus implementation freedom.
• How much of artifact ordering, numbering, and layout is normative at PBS level versus owned purely by PBX authority.
• Whether compilers should emit final INTRINSIC <id> directly for a selected VM line or may emit a declaration-based preload form such as INTRCALL <decl_index>.
• Whether a separate debug/source-map surface is part of v1.

8. Non-Goals

• Repeating the full PBX or ISA documentation.
• Mandating one binary-emitter implementation strategy.
• Defining loader patching internals already owned elsewhere.

9. Exit Criteria

This document is ready to move beyond skeleton status only when:

1. the PBS-to-artifact boundary is explicit,
2. artifact-level invariants needed by verifier and loader are normative,
3. the document no longer relies on unresolved A Ver items for ordinary v1 artifact mapping behavior.