378 lines
13 KiB
Markdown
378 lines
13 KiB
Markdown
# VM-owned vs Host-backed
|
|
|
|
Status: Draft v1 (Temporary)
|
|
Applies to: ownership classification of PBS-visible operations, runtime boundary selection, and the normative distinction between VM-defined semantics and host-provided services
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the normative distinction between:
|
|
|
|
- VM-owned operations,
|
|
- host-backed operations,
|
|
- and user-defined program operations.
|
|
|
|
Its purpose is to prevent semantic drift between:
|
|
|
|
- builtin language behavior,
|
|
- VM execution behavior,
|
|
- host/platform integration,
|
|
- and source-level surfaces that may look similar while belonging to different ownership domains.
|
|
|
|
This document exists because PBS must distinguish at least three different kinds
|
|
of callable behavior:
|
|
|
|
- program-owned functions,
|
|
- VM-owned intrinsic behavior,
|
|
- host-backed services.
|
|
|
|
Without this distinction, the language would conflate:
|
|
|
|
- builtin semantics with syscalls,
|
|
- source-level shells with runtime authority,
|
|
- and VM contracts with host capability-gated services.
|
|
|
|
## 2. Scope
|
|
|
|
This document defines:
|
|
|
|
- the ownership model for callable behavior visible to PBS programs,
|
|
- the normative difference between VM-owned and host-backed operations,
|
|
- the runtime boundary crossed by each operation category,
|
|
- the relationship between ownership and lowering form,
|
|
- the relationship between ownership and determinism,
|
|
- the relationship between ownership and capability checks,
|
|
- the relationship between ownership and loader resolution,
|
|
- and the classification rule used to decide whether a surface belongs to the VM or to the host.
|
|
|
|
This document does not define:
|
|
|
|
- the full parser grammar for builtin declarations,
|
|
- the full intrinsic registry binary format,
|
|
- the final PBX section numbering for intrinsic metadata,
|
|
- subsystem-specific host APIs such as GFX or AUDIO,
|
|
- or the complete dynamic semantics of every builtin type.
|
|
|
|
## 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. `1. Language Charter.md`
|
|
4. `3. Core Syntax Specification.md`
|
|
5. `4. Static Semantics Specification.md`
|
|
6. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
7. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
8. This document
|
|
|
|
If a rule here conflicts with higher-precedence authority, the higher-precedence
|
|
authority wins.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `1. Language Charter.md`
|
|
- `3. Core Syntax Specification.md`
|
|
- `4. Static Semantics Specification.md`
|
|
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
|
|
## 5. Core Ownership Model
|
|
|
|
PBS distinguishes three ownership categories for callable behavior.
|
|
|
|
### 5.1 Program-owned function
|
|
|
|
A program-owned function is authored by the program and compiled from a PBS body.
|
|
|
|
Properties:
|
|
|
|
- semantic ownership belongs to the program,
|
|
- execution stays inside the VM,
|
|
- source definition includes an executable body,
|
|
- runtime dispatch uses ordinary function-call machinery,
|
|
- authority does not depend on host capability grants.
|
|
|
|
### 5.2 VM-owned operation
|
|
|
|
A VM-owned operation is part of the semantic contract of the PBS platform.
|
|
|
|
Properties:
|
|
|
|
- semantic ownership belongs to the VM platform,
|
|
- execution stays inside the VM,
|
|
- behavior is not defined by user-authored PBS bodies,
|
|
- behavior is not resolved against host registries,
|
|
- behavior is not granted or denied by host capabilities,
|
|
- and behavior is expected to remain semantically canonical across conforming implementations.
|
|
|
|
VM-owned operations include, at minimum:
|
|
|
|
- intrinsic operations over builtin types,
|
|
- compiler-recognized intrinsic method-call surfaces over core semantic forms,
|
|
- and other future VM-defined semantic helpers explicitly designated by spec.
|
|
|
|
### 5.3 Host-backed operation
|
|
|
|
A host-backed operation is provided by the runtime environment outside the VM's
|
|
closed semantic domain.
|
|
|
|
Properties:
|
|
|
|
- semantic authority belongs to the host platform,
|
|
- execution crosses the VM-to-host boundary,
|
|
- resolution uses canonical host identity,
|
|
- loader validation and capability checks are required before execution,
|
|
- and the final executable form is numeric host dispatch.
|
|
|
|
Host-backed operations are the domain of `declare host`, PBX `SYSC`, loader
|
|
resolution, and final `SYSCALL`.
|
|
|
|
## 6. The Boundary Question
|
|
|
|
The normative classification question is:
|
|
|
|
```text
|
|
Does this operation belong to the VM's semantic contract, or does it require a
|
|
service owned by the external host platform?
|
|
```
|
|
|
|
Rules:
|
|
|
|
- If the operation expresses builtin language or VM semantics, it is VM-owned.
|
|
- If the operation requires host-provided authority, devices, or platform services, it is host-backed.
|
|
- If the operation is implemented by ordinary source code in the current program, it is program-owned.
|
|
|
|
Heuristic:
|
|
|
|
- if the operation must still have a complete meaning in a host-minimal VM, it is VM-owned,
|
|
- if the operation loses meaning without external platform service, it is host-backed.
|
|
|
|
Examples:
|
|
|
|
- `Vec2.dot(other)` is VM-owned,
|
|
- `Color.rgb(r, g, b)` is VM-owned,
|
|
- `optional.hasSome()` is VM-owned,
|
|
- `enumValue.name()` is VM-owned,
|
|
- `Gfx.draw_pixel(x, y, c)` is host-backed,
|
|
- `Input.is_pressed(button)` is host-backed.
|
|
|
|
## 7. Runtime Boundary and Resolution Model
|
|
|
|
### 7.1 VM-owned operations
|
|
|
|
VM-owned operations do not cross the host boundary.
|
|
|
|
Rules:
|
|
|
|
- they do not resolve through the host syscall registry,
|
|
- they do not emit `SYSC`,
|
|
- they do not require loader-side capability checks,
|
|
- they are not represented by `declare host`,
|
|
- and they execute through VM-owned machinery such as intrinsic dispatch or other VM-defined execution paths.
|
|
|
|
### 7.2 Host-backed operations
|
|
|
|
Host-backed operations cross the VM boundary and require host authority.
|
|
|
|
Rules:
|
|
|
|
- they resolve by canonical host identity `(module, name, version)`,
|
|
- they are represented in source through reserved host-binding surfaces,
|
|
- they emit PBX host-binding metadata,
|
|
- they are validated against authoritative host metadata during load,
|
|
- and they execute in final form through `SYSCALL`.
|
|
|
|
## 8. Semantic Authority
|
|
|
|
The semantic owner of an operation is the layer that defines its normative
|
|
meaning.
|
|
|
|
### 8.1 VM-owned semantic authority
|
|
|
|
For VM-owned operations:
|
|
|
|
- the VM platform defines the operation's meaning,
|
|
- the frontend may expose shell declarations but does not define behavior,
|
|
- the host runtime must not redefine the operation's language-level semantics,
|
|
- and the HAL may consume produced values but must not own their semantic definition.
|
|
|
|
### 8.2 Host-backed semantic authority
|
|
|
|
For host-backed operations:
|
|
|
|
- the host platform defines the authoritative service identity and ABI,
|
|
- the frontend exposes a compile-time shell only,
|
|
- the loader resolves the shell's canonical identity against the host registry,
|
|
- and the VM executes only the numeric form after loader patching.
|
|
|
|
## 9. Determinism and Environmental Dependence
|
|
|
|
Determinism requirements differ by ownership category.
|
|
|
|
### 9.1 VM-owned operations
|
|
|
|
VM-owned operations must not derive meaning from host service behavior.
|
|
|
|
Rules:
|
|
|
|
- a VM-owned operation must not call the host as part of its semantic definition,
|
|
- a VM-owned operation must not require host capability grants,
|
|
- a VM-owned operation must not depend on wall-clock time unless a higher-precedence authority explicitly allows it,
|
|
- a VM-owned operation must not depend on frontend-generated helper algorithms for its canonical behavior,
|
|
- and the VM contract must be specific enough that conformance can test its behavior.
|
|
|
|
This does not require every VM-owned operation to be mathematically pure.
|
|
It does require the operation's meaning to be owned and specified by the VM
|
|
contract rather than delegated to the host.
|
|
|
|
### 9.2 Host-backed operations
|
|
|
|
Host-backed operations may depend on host state, devices, permissions, or
|
|
platform policy.
|
|
|
|
Rules:
|
|
|
|
- host-backed operations may be denied by capability policy,
|
|
- host-backed operations may vary by platform implementation within their ABI contract,
|
|
- and host-backed operations are not reclassified as VM-owned merely because the source surface resembles an ordinary method call.
|
|
|
|
## 10. Artifact Implications
|
|
|
|
Ownership classification determines artifact form.
|
|
|
|
### 10.1 Program-owned function artifact direction
|
|
|
|
Program-owned functions lower to ordinary program call machinery.
|
|
|
|
### 10.2 VM-owned artifact direction
|
|
|
|
VM-owned operations lower to VM-facing artifacts.
|
|
|
|
Illustrative forms:
|
|
|
|
- direct intrinsic ids such as `INTRINSIC <id>`,
|
|
- temporary intrinsic declaration tables plus pre-resolution callsites,
|
|
- or other VM-internal runtime forms explicitly defined by future spec.
|
|
|
|
Rules:
|
|
|
|
- VM-owned operations must not be encoded as host-binding metadata merely because they are not authored in user code,
|
|
- and VM-owned operations must not require host registry lookup.
|
|
|
|
### 10.3 Host-backed artifact direction
|
|
|
|
Host-backed operations lower to host-facing artifacts.
|
|
|
|
Rules:
|
|
|
|
- host-backed operations emit host-binding declarations into `SYSC`,
|
|
- host-backed callsites use `HOSTCALL <sysc_index>` before load,
|
|
- the loader resolves and patches those callsites,
|
|
- and final execution uses `SYSCALL <id>`.
|
|
|
|
## 11. Source Surface Similarity Does Not Collapse Ownership
|
|
|
|
Two source surfaces may look similar while belonging to different ownership
|
|
domains.
|
|
|
|
Examples:
|
|
|
|
- `Vec2.length()` may be VM-owned,
|
|
- `Gfx.clear(color)` may be host-backed,
|
|
- `value.name()` over an enum may be VM-owned,
|
|
- and `service.method()` may be program-owned or service-owned ordinary PBS behavior.
|
|
|
|
Rules:
|
|
|
|
- source-level method-call syntax does not determine ownership,
|
|
- declaration shape does not determine ownership,
|
|
- ownership is determined by semantic authority and runtime boundary,
|
|
- and toolchain metadata must classify the operation explicitly where ambiguity could arise.
|
|
|
|
## 12. Relationship to `declare host`
|
|
|
|
`declare host` is reserved exclusively for host-backed surfaces.
|
|
|
|
Rules:
|
|
|
|
- `declare host` must not be reused to model VM-owned builtin semantics,
|
|
- host attributes such as `Host(module, name, version)` must not be used to identify VM-owned intrinsic behavior,
|
|
- and a source surface that represents VM-owned behavior must use VM-specific metadata and lowering rules.
|
|
|
|
Rationale:
|
|
|
|
- `declare host` communicates external service ownership,
|
|
- host attributes communicate loader-facing canonical identity,
|
|
- and reusing them for VM-owned behavior would incorrectly imply host resolution, capability gating, and host semantic authority.
|
|
|
|
## 13. Relationship to Builtin Types and Intrinsics
|
|
|
|
Builtin types are VM-facing semantic types.
|
|
|
|
Rules:
|
|
|
|
- builtin types are not host APIs,
|
|
- builtin type operations that belong to the builtin domain are VM-owned,
|
|
- builtin constants, projections, constructors, and intrinsic methods are classified by VM semantics rather than by host service ownership,
|
|
- and builtin values may later be passed to host-backed operations without transferring semantic ownership of the type itself.
|
|
|
|
Example:
|
|
|
|
- `Color` is VM-owned as a semantic type,
|
|
- `Color.rgb(...)` is VM-owned,
|
|
- `Pixel` may contain `Color` in its builtin layout,
|
|
- `Gfx.draw_pixel(x, y, c)` is host-backed even when `c` has a VM-owned builtin type.
|
|
|
|
## 14. Relationship to `stdlib` and SDK Surfaces
|
|
|
|
`stdlib` and SDK packaging expose compile-time surfaces.
|
|
|
|
Rules:
|
|
|
|
- SDK or stdlib shells may expose both VM-owned and host-backed surfaces,
|
|
- shell placement alone does not determine runtime ownership,
|
|
- the runtime-facing artifact contract must preserve the true ownership category,
|
|
- and compile-time convenience must not collapse VM-owned and host-backed operations into the same runtime mechanism.
|
|
|
|
## 15. Classification Checklist
|
|
|
|
When introducing a new callable surface, the spec author or toolchain author
|
|
must answer at least these questions:
|
|
|
|
1. Who owns the semantic meaning of this operation?
|
|
2. Does the operation require host-provided authority, devices, or policy?
|
|
3. Must the loader resolve the operation against an external registry?
|
|
4. Can the operation be denied by capabilities?
|
|
5. Should the operation continue to exist with complete meaning in a host-minimal VM?
|
|
6. Is the operation part of builtin language semantics rather than platform service integration?
|
|
|
|
Classification rule:
|
|
|
|
- If answers 2, 3, or 4 are yes, the operation is host-backed.
|
|
- If answer 6 is yes and 2, 3, and 4 are no, the operation is VM-owned.
|
|
- Otherwise the operation is program-owned unless another spec defines a distinct category.
|
|
|
|
## 16. Conformance Expectations
|
|
|
|
Conforming implementations must preserve the ownership boundary.
|
|
|
|
Rules:
|
|
|
|
- an implementation must not lower VM-owned builtin semantics through the host syscall pipeline,
|
|
- an implementation must not treat host-backed operations as if they were VM-defined intrinsic semantics,
|
|
- an implementation must preserve the loader-facing host-binding contract for host-backed surfaces,
|
|
- and an implementation must preserve VM-facing semantic ownership for builtin and intrinsic operations.
|
|
|
|
## 17. Current Decision Summary
|
|
|
|
The current model is:
|
|
|
|
1. Program-authored functions are program-owned and execute through ordinary call machinery.
|
|
2. Builtin semantics and intrinsic behavior are VM-owned.
|
|
3. External platform services are host-backed.
|
|
4. VM-owned behavior must not be modeled as `declare host`.
|
|
5. Host-backed behavior must continue to use canonical host identity, `SYSC`, loader resolution, and final `SYSCALL`.
|
|
6. Ownership is determined by semantic authority and runtime boundary, not by source-level syntax resemblance.
|