clean up and update docs (agenda, decisions, PRs, learn and specs)

This commit is contained in:
2026-03-24 13:40:55 +00:00
parent d5eb5cf033
commit 03494c8cd7
11 changed files with 62 additions and 964 deletions
@@ -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`