# Host Memory Boundary Decision

Status: Accepted (Implemented)
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.