# 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. `13. Lowering IRBackend 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`
- `13. Lowering IRBackend 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`.
- V1 source-attribution hooks for diagnostics/conformance need only support recovery of at least one source location for source-attributable backend failures; one exact source-map format is not yet required.

## 6. Current Conformance-Facing Mapping Baseline

The current boundary across backend-facing specs is:

- `13. Lowering IRBackend Specification.md` defines what facts must be preserved by lowering,
- this document defines how the PBS-facing artifact facts appear in PBX/bytecode-visible form,
- and `19. Verification and Safety Checks Specification.md` defines later validity checks after the artifact is formed and, where relevant, patched by the loader.

The current conformance-facing artifact baseline is invariant-based.

At minimum, the PBS-facing artifact contract currently includes:

1. canonical host-binding declarations in `SYSC` for admitted host-backed uses;
2. `SYSC` deduplication by canonical identity and ordering by first occurrence;
3. host-backed callsites emitted in pre-load form as `HOSTCALL <sysc_index>`;
4. no host-binding metadata emission for VM-owned builtin projections, builtin constants, or intrinsic callsites;
5. no executable bytecode emission for stdlib interface modules by themselves;
6. enough source-attribution information to recover at least one source location for backend failures that remain in the PBS-facing diagnostics/conformance surface.

This baseline does not require one full-image PBX golden.

## 7. 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.

## 8. TODO

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>`.
- Which richer debug/source-map surfaces, if any, are added beyond the minimum attribution hooks already sufficient for v1 diagnostics and conformance.

## 9. Non-Goals

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

## 10. 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 `TODO` items for ordinary v1 artifact mapping behavior.