prometeu-studio/docs/pbs/decisions/Host Memory Boundary Decision.md

Host Memory Boundary Decision

Status: Accepted Cycle: Initial host-boundary closure pass

1. Context

PBS needs a user-visible contract for the boundary between VM-owned semantics and host-provided runtime services.

At the current stage of the language, userland does not expose complex host-owned resource models. The runtime offers features and the frontend consumes them; PBS should be careful not to project unnecessary language-level memory abstractions into runtime internals too early.

2. Decision

PBS v1 adopts the following host-memory boundary baseline:

1. Cross-boundary interaction between host and PBS userland is restricted to stack-only values.
2. PBS userland does not expose host memory as ordinary language values.
3. Raw pointers are not exposed in PBS userland.
4. Borrowed host-memory views are not exposed in PBS userland.
5. Pinning is not exposed in PBS v1.
6. Zero-copy transfer is not exposed in PBS v1.
7. Heap-shared boundary values between host and PBS userland are not part of the v1 model.
8. Long-lived host resources, if later exposed, must be specified explicitly by subsystem contract rather than inferred from a general host-memory model.

3. Boundary Rule

The host/userland boundary in PBS v1 is value-based rather than memory-sharing-based.

This means:

• host-backed interaction happens through explicit call boundaries,
• data crossing that boundary is limited to stack-only value forms,
• and userland never receives direct access to host-owned memory regions.

PBS therefore does not model host memory as something the language can directly hold, borrow, pin, or traverse.

4. What Is Not Exposed

PBS v1 does not expose any general userland model for:

• raw host pointers,
• borrowed host slices or views,
• pinned host memory,
• zero-copy host/userland transfer,
• shared heap objects spanning host memory and VM memory.

These features are out of scope for the v1 language model.

5. Role of Syscalls

At the current stage, host interaction should be understood primarily through syscall-style host-backed contracts.

Those contracts may accept and return stack-only values, but they do not imply that PBS userland owns, borrows, or directly manipulates host memory.

6. Long-Lived Host Resources

PBS v1 does not yet define a general-purpose language model for long-lived host-owned resources such as:

• banks,
• mixers,
• or other subsystem-specific retained resources.

If such resources are exposed later, they must be specified by explicit subsystem contract rather than by assuming a general host-memory-handle model in core PBS.

7. Failure Model Scope

This decision does not force a universal language-level error projection for all runtime-internal host behavior.

It only closes the memory-boundary side of the question:

• PBS userland does not directly manipulate host memory,
• and cross-boundary interaction remains stack-value-based.

Concrete error modeling for particular host-backed surfaces belongs to the contract of those surfaces rather than to a general raw-memory boundary rule.

8. Invariants

• The host/runtime may own internal memory and resource lifetimes that PBS userland never sees directly.
• PBS userland remains insulated from host-memory unsoundness by not exposing raw memory access at the language level.
• The absence of pointers and borrowed host views is a core v1 safety property.
• Boundary simplicity takes priority over premature expressiveness in this area.

9. Beginner-Facing Model

The user-facing explanation should be:

• the runtime can provide services to PBS programs,
• programs pass ordinary values into those services and receive ordinary values back,
• but programs do not directly hold or manipulate host memory.

10. Explicit Non-Decisions

This decision record does not yet close:

• the future design of subsystem-specific long-lived host resources,
• the future design of any explicit resource-release APIs,
• the concrete error contract of each host-backed surface,
• the final wording of host-boundary diagnostics.

11. Spec Impact

This decision should feed at least:

• docs/pbs/specs/10. Memory and Lifetime Specification.md
• docs/pbs/specs/6. VM-owned vs Host-backed.md
• docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md

12. Validation Notes

The intended split is:

• runtime and host internals may remain complex,
• PBS userland sees only stack-only value exchange across the boundary,
• and any richer host-resource model must be introduced later by explicit subsystem contract.