Historical VM Core and Assets (Retired Decisions)

This document consolidates the historical rationale and mental models from retired decisions regarding VM-owned stateful core, byte transfer protocol, filesystem fault policies, and asset management.

Status: Pedagogical / Historical (not normative).

1. VM-Owned Stateful Core and Byte Transfer

Rationale for Stateful Core (Retired Decision 006)

Problem: Lack of a canonical contract for stateful VM-owned resources led to divergence in handles, lifecycles, and ABI shapes.
Solution: Represent stateful resources as HeapRef<TBuiltinState> with anti-stale mechanisms (index + generation).
Lifecycle: Every stateful domain must explicitly define create, read/query, update, and destroy.
Fault Model: Trap for structural errors (invalid ABI, stale handles), status for domain operational failures.

Rationale for Byte Transfer Protocol (Retired Decision 003)

Goal: Establish a canonical protocol for moving bytes between host and guest without binary-to-string conversion or host-owned handles.
Protocol: Uses Value::Byte as a primitive and HeapRef(Byte) (ObjectKind::Bytes) as the canonical buffer.
Signatures:
- read(host_handle, host_offset, dst_ref, dst_offset, max_bytes) -> (status, bytes_transferred, eof)
- write(host_handle, host_offset, src_ref, src_offset, max_bytes) -> (status, bytes_transferred)
Impact: Unified data plane for fs and data banks, giving the guest explicit control over memory.

2. Filesystem Fault Policy (Retired Decision 007)

Core Policy

Trap: Structural violations (invalid signatures, dead HeapRefs, invalid byte windows).
Status: Operational conditions (not found, access denied, storage full, transient backend errors).
No Partial Success: write operations must not report silent partial success; failure to complete the full contract results in a domain failure status.

3. Asset Management and `assets.pa` Contract

Autocontained Runtime Contract (Retired Decision 011)

Transition: Moved from fragmented manifest.json + assets.pa to a single autocontained assets.pa artifact.
Envelope v1: Fixed binary prelude + JSON header (asset_table + preload) + Binary payload.
Memory Efficiency: The runtime must not require the entire payload to be resident in RAM; slices are resolved using offsets relative to the payload region.

Preload and Identity (Retired Decision 012)

Identity: PreloadEntry moved from name-based to ID-based ({ asset_id, slot }).
Semantics: asset_id follows Java int (32-bit signed) semantics to ensure cross-platform compatibility.
Validation: Preload is validated during bootstrap against the asset_table. Invalid IDs or slot clashes (same bank_type and slot) are structural errors that abort boot.

References

Specs:
- ../specs/15-asset-management.md
- ../specs/16-host-abi-and-syscalls.md
- ../specs/16a-syscall-policies.md
Source Decisions (Archived):
- 003-vm-owned-byte-transfer-protocol.md
- 006-vm-owned-stateful-core-contract.md
- 007-filesystem-fault-core-policy.md
- 011-assets-pa-autocontained-runtime-contract.md
- 012-assets-preload-asset-id-contract.md

3.4 KiB Raw Blame History