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