116 lines
4.5 KiB
Markdown
116 lines
4.5 KiB
Markdown
# 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.
|