clean up and update docs (agenda, decisions, PRs, learn and specs)
This commit is contained in:
@@ -0,0 +1,53 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user