---
id: LSN-0008
ticket: legacy-runtime-learn-import
title: Historical VM Core and Assets (Retired Decisions)
created: 2026-03-27
tags: [migration, tech-debt]
---

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