SLeeLa Runtime Services Contract
Purpose
The SLVM generations share one language and one source-defined ISA, but the VM needs more than opcode dispatch. Networking, file I/O, sockets, process/thread execution, memory reclamation, and shutdown must have explicit lifecycle contracts.
This document is the common runtime-services construction for SLVM/1 through SLVM/11. It supplements the opcode map; it does not add hidden opcodes.
Services
| Service | Contract |
|---|---|
| Networking | Address resolution, connection/listen/accept, nonblocking readiness, deadlines, cancellation, backpressure, bounded buffers, protocol errors, and capability checks. |
| File I/O | Opaque VM handles, open/read/write/close/unlink, explicit ownership, EOF/error distinction, atomic close, platform adapters, and recovery-safe invalidation. |
| Sockets | Sockets are resources with states: NEW, BOUND, LISTENING, CONNECTING, CONNECTED, HALF_CLOSED, CLOSING, CLOSED, FAILED. Native descriptors/handles never escape the VM. |
| OS system calls | Host System API access (environment, identity, working directory, filesystem metadata, and process execution) through the OP_OS_* opcodes / os* built-ins, serviced by impl/core/sleela_os.c on Windows (Win32), Linux, and macOS (POSIX). A spawned child process is a resource with states NEW, RUNNING, EXITED, FAILED, tracked as a VM-local bounded handle (never a raw PID/HANDLE); it is reaped by osWait/osProcessClose and force-released at VM teardown. |
| Threading | Structured concurrency: every spawned execution has an owner/scope, cancellation token, join/detach policy, deadline, and terminal result. Unowned threads are rejected. |
| Garbage Collection | VM-managed heap objects use tracing reachability as the semantic baseline. Collection is incremental/generational where practical, with safepoints and write barriers. Native resources are not reclaimed by GC alone. Implemented in runtime/garbage_collector.c; verified and open points are in impl/RUNTIME-AUDIT.md. |
| Teardown | Shutdown is idempotent and ordered: stop admission, cancel child work, quiesce I/O, close sockets/files, join owned threads, drain deferred work, run finalizers for language objects, then release VM memory. |
| Recovery | Stale handles and resources from an invalidated epoch fail closed and must be reacquired. Recovery never silently resurrects a native descriptor. |
Modern execution model
1. Structured concurrency
SPAWN creates a child execution owned by the current VM scope. JOINALL is the legacy bulk-join primitive; the runtime service model additionally requires:
- cancellation propagation from parent scope to children;
- a join result for every child;
- no implicit detached execution;
- bounded worker/resource accounting;
- deadlines and cooperative cancellation at blocking points;
- safe-point participation before shutdown.
The existing pthread/Windows abstraction remains an OS adapter, not the language concurrency model.
2. Async-capable I/O
The language may retain synchronous source operations while the runtime service layer supports asynchronous implementations underneath them. Blocking operations must therefore be represented as cancellable resource waits rather than assuming that a native thread can always be abandoned.
The native backend may use poll/select/epoll/kqueue/IOCP or another platform appropriate mechanism. These are implementation choices; the SLeeLa semantic contract remains stable.
3. Resource ownership
Every file, socket, pipe, FIFO, network connection, thread, and pending I/O request has one explicit owner/scope and one terminal lifecycle. Close/cancel operations are idempotent. Double-close, use-after-close, stale-handle, and wrong-owner access return a runtime error rather than operating on a recycled native resource.
4. Garbage collection and native resources
GC manages language-visible heap objects. It does not make native OS resources implicitly safe to abandon.
A resource-owning object must have an explicit close/release path. Finalization is a backstop for language objects, not the primary mechanism for sockets, files, threads, or other scarce OS resources.
The collector should use:
- generational collection for short-lived allocations;
- incremental marking/sweeping to limit pause time;
- precise roots where type information permits;
- write barriers for old-to-young and incremental marking edges;
- VM safepoints at allocation, call/return, loop/back-edge, blocking I/O, and explicit yield/cancellation boundaries;
- allocation/resource budgets integrated with the SLVM memory/resource managers.
5. Networking and sockets
Networking is capability-mediated. A connection must carry its address family, transport, peer/local identity, timeout/deadline, cancellation state, and lifecycle epoch.
Reads/writes distinguish:
- successful progress;
- orderly EOF/peer close;
- retryable readiness;
- timeout/cancellation;
- permanent transport failure.
A close transitions the resource toward CLOSED and wakes pending waiters. Half-close is represented explicitly where the transport supports it.
6. File I/O
File handles are opaque VM-local capabilities. Native descriptor numbers and Windows HANDLE values remain private to the platform adapter.
Open/read/write/close are subject to:
- capability and path policy;
- ownership;
- cancellation/deadline where the platform permits;
- short-read/short-write handling;
- EOF/error distinction;
- generation/identity checks for recovery;
- deterministic close during teardown.
This builds on the existing impl/fileio platform boundary and SLVM/9 filesystem identity model.
7. Teardown state machine
RUNNING -> QUIESCING -> CANCELLING -> DRAINING -> JOINING -> CLOSING_RESOURCES -> FINALIZING -> STOPPED
Any unrecoverable lifecycle violation moves to QUARANTINED rather than reopening or silently reusing a resource.
The sequence is idempotent: repeated shutdown requests observe the current state and do not execute destruction twice.
Mapping to the 156-opcode ISA
The existing ISA already contains direct primitives for:
- threading:
SPAWN,JOINALL,LOCK,UNLOCK,SEND,RECV; - sockets:
LISTEN,ACCEPT,CONNECT,SOCKREAD,SOCKWRITE,SOCKCLOSE; - pipes/FIFOs:
PIPE,PIPEPEER,FIFO_MK; - files:
FILEOPEN,FILEREAD,FILEWRITE,FILECLOSE,FILEUNLINK; - asynchronous/synchronization facilities:
SYN_*,MUN_*; - OS system calls:
OS_PLATFORM,OS_CAPABILITY,OS_GETENV,OS_SETENV,OS_CWD,OS_CHDIR,OS_HOSTNAME,OS_USERNAME,OS_TEMPDIR,OS_PID,OS_EXISTS,OS_ISDIR,OS_FILESIZE,OS_MKDIR,OS_REMOVE,OS_RENAME,OS_RUN,OS_SPAWN,OS_WAIT,OS_KILL,OS_PCLOSE(theOP_OS_*group, codes 103–123), plus OSLS metadata/inspection bindings throughOP_OSLS_CALL(155).
The OSLS call opcode dispatches 12 typed osls_* functions through a stable operation-ID table and returns bounded JSON Strings; C pointers and native record layouts never enter VM values. The OS process opcodes (OS_SPAWN/OS_WAIT/OS_KILL/OS_PCLOSE) reuse the same resource-ownership discipline as sockets and files: a spawned child is a VM-local bounded handle with an explicit terminal lifecycle, reaped on wait/close and released during teardown. GC, cancellation, ownership, deadlines, resource epochs, and teardown remain runtime services rather than one opcode per concept. This avoids bloating the ISA while allowing the native implementation and every VM generation to evolve.
Generation responsibilities
- SLVM/1: establish resource ownership, thread, socket, file, and VM teardown invariants at the execution boundary.
- SLVM/2–3: preserve those invariants through cryptographic, isolation, and verification layers.
- SLVM/4–6: carry ownership, cancellation, resource epochs, lineage, leases, and migration state across distributed execution.
- SLVM/7: integrate memory, resource, checkpoint, health, and recovery managers.
- SLVM/8: enforce admission, policy, capability leases, transactions, audit, supervision, and cancellation.
- SLVM/9: bind file resources to filesystem identity/generation and native adapters.
- SLVM/10: revalidate storage/resource identity before verified execution.
- SLVM/11: apply the same ownership and lifecycle rules to filesystem modules.
All generations preserve the same SLeeLa source semantics. A generation may add stronger validation or more capable adapters, but it must not weaken resource lifetime, cancellation, safety, or teardown guarantees.
Because the OP_OS_* system-call group is part of the one shared ISA, the host
System Call API is available to every generation, SLVM/1 through SLVM/11 —
not only the base VM. Each generation applies its existing resource-ownership
and teardown rules to spawned processes exactly as it does to sockets and files
(e.g. SLVM/8 enforces capability leases and audit over OS_RUN/OS_SPAWN;
SLVM/9–11 bind process and filesystem-metadata calls to the storage-identity
model). A generation may restrict or sandbox the OS surface via capability
policy, but it inherits the same os* semantics the base VM exposes.
Standard GC implementation
The previous runtime GC placeholder has been replaced by the common collector in runtime/garbage_collector.c. It is a stable-handle, generational incremental tracer with explicit roots, safepoints, SATB-style pre-write protection, remembered old-to-young references, promotion, and deterministic full collection. The Core VM now owns one collector and treats struct instances as managed objects.
The C++ VM generations use lib/vm/include/sleela_vm_gc.hpp as an RAII facade over the same C collector. The source-side declarations are in lib/vm/GarbageCollector.sleela, GCObject.sleela, GCQuality.sleela, GCPermutation.sleela, GCRoot.sleela, and GCBarrier.sleela.
Collection is deliberately non-moving because the current SLeeLa value model uses stable VM-local handles. This avoids relocation complexity while preserving the modern collector invariants. Native sockets, files, threads and other OS resources remain governed by the resource-ownership/teardown layer rather than by GC reachability.