Home/Modules/os-level-support

os-level-support

library module lib/os-level-support

SLeeLa OS-Level Support Source Package

This directory is the SLeeLa source-language catalogue and VM-facing organization for the native OS support layer. It is divided into a general vocabulary, portable/common API, VM integration contract, and OS-specific backend catalogues.

Source elements

Source filePurpose
SLPackage.sleelaPackage entry point and component names
SLOsSupportCatalog.sleelaCanonical capability groups, common API names, runtime/module functions, planned portable functions, and grouping terms
SLOsSupportElement.sleelaReusable element descriptor: group, VM term/opcode, portable symbol, native symbol, backend, effect, status and arity
SLOsSupportVMElements.sleelaFactory methods for the 21 existing OP_OS operations, mapped to VM opcodes and slos_* backend symbols
SLOsSupportOSLSElements.sleelaFactory methods for the 25 registered osls_* C ABI calls, mapped to OP_OSLS_CALL (155) and operation IDs 0–24 (the original 12 plus 13 read-only inspection calls added in revision 1.1: memory, disk, volume, system load, capabilities, runtime-info, native-error, path normalize/join/resolve/info, and hostname resolution)
SLOsSupportVMBridge.sleelaVM dispatch stages, status/marshalling vocabulary and current VM opcode mapping
examples/SLOsSupportCatalogExample.sleelaExample that enumerates common groups, VM bindings, and each platform's native API catalogue
SLOsSupportLinux.sleelaLinux grouping terms and alphabetized POSIX/Linux native symbols
SLOsSupportWindows.sleelaWindows grouping terms and alphabetized Win32/Winsock symbols
SLOsSupportMacOS.sleelamacOS grouping terms and alphabetized Darwin/POSIX/Mach symbols
SLOsSupportLinuxSource.sleelaLinux source facade with VM-backed portable calls and gated Linux extension metadata
SLOsSupportWindowsSource.sleelaWindows source facade with VM-backed portable calls and gated Win32/Winsock extension metadata
SLOsSupportMacOSSource.sleelamacOS source facade with VM-backed portable calls and gated Darwin/Mach/framework extension metadata
SLOsSupportPlatform.sleelaRuntime platform selector for the Linux, Windows and macOS source facades
SLOsSupportNative.sleelaSource facade for the 12 VM-callable OSLS functions; returns JSON Strings with OSLS status. PID and epoch arguments are long (int64) to match the C ABI
SLOsSupportTyped.sleelaTyped-result binding catalogue: pairs each record-returning OSLS call with the lib/systems record class that models its JSON fields (SLSystemInfo, SLProcessInfo, SLFileInfo, SLCPUInfo, SLTimezoneInfo, SLNetworkInterface)
SLOsSupportStatus.sleelaCore status values for the osls_* ABI, matching osls_status in os-level-support/osls.h (OK, INVALID_ARGUMENT, BUFFER_TOO_SMALL, SYSTEM_ERROR, NOT_FOUND, UNSUPPORTED)
SLOsRuntimeStatus.sleelaIn-process runtime status values, matching slosh_status / osls_runtime_status (adds OUT_OF_MEMORY, CAPACITY, BUSY, CALLBACK_FAILED) — a distinct space from the core ABI
SLOsEvent / SLOsSubscription / SLOsTaskQueue.sleelaDescriptive contract records for the in-process runtime event, subscription and cooperative task queue
examples/SLOsSupportConsistencyExample.sleelaRunnable round-trip guard: asserts the 12 OSLS element factories agree with the native registry, the core/runtime status maps round-trip, and the typed bindings name a known record class

Two status spaces (do not conflate)

The OSLS subsystem has two distinct status enums, and the SLeeLa catalogue now models them with two distinct classes:

The two spaces share only OK, INVALID_ARGUMENT and NOT_FOUND; the rest differ, so a value from one must never be interpreted with the other.

Canonical grouping vocabulary

The catalog uses stable terms such as:

These are source-level grouping identifiers, not native function names. Use them as the semantic group of an OS-support element; use the platform catalogues for native symbols and SLOsSupportElement to describe an individual binding. SLOsSupportVMElements supplies ready-made descriptors for the current VM OS calls. SLOsSupportOSLSElements supplies descriptors for the 12 registered root osls_* calls; each maps to the single OP_OSLS_CALL opcode plus a stable operation ID.

VM integration boundary

The SLeeLa VM already has an OS system-call path:

The new source catalogues now reference that existing VM bridge and enumerate its exact opcode names and numbers. SLOsSupportVMElements maps each existing VM operation to its OP_OS opcode and the corresponding slos_* C backend symbol. They do not create a second VM syscall path or duplicate opcode numbers.

The root C library under os-level-support/ now has a VM-callable adapter: os-level-support/osls_vm_bridge.c registers all 12 declared osls_* APIs with stable operation IDs 0–11. Each registry row contains a callable native invocation function, native symbol identity, argument type vector, result type, and required capability mask. The compiler lowers the osls... source built-ins to append-only opcode OP_OSLS_CALL=155. The VM resolves the registry entry, validates arity and each stack value's type, enforces the VM-local host-read capability (host embeddings may revoke it with slvm_set_osls_capabilities; read-only inspection is the default), invokes the registered function pointer, and marshals records and collections into bounded JSON Strings containing an OSLS status code. Native pointers and C struct layouts never cross the VM boundary. SLOsSupportOSLSElements now records these real bindings rather than UNREGISTERED.

The CMake package and the SLeeLa VM Makefile both compile the adapter and the existing OSLS platform implementation. test_osls_vm_bridge exercises native symbol resolution, callable entries, typed argument/result marshalling, denied capabilities, invalid signatures, and bounded-result failures; make -C impl test-osls-vm exercises the VM built-ins and verifies runtime rejection of an invalid argument type. Windows network-interface enumeration currently reports OSLS_UNSUPPORTED; unsupported or unavailable platform details remain explicit status results.

OS-specific source support

The three *Source.sleela classes are executable source-level facades for the portable operations already exposed by the VM (host/user identity, working directory, temporary directory, environment access, path existence/type and file size). Their platform metadata includes path separators, line endings, executable suffixes, capability groups and native extension symbol lists. SLOsSupportPlatform detects the host and selects a backend identifier. It fails closed for an unknown platform.

The common OSLS API is registered and callable through the VM: 25 read-only operations (IDs 0–24) as of revision 1.1. State-changing and handle/stream families (file mutation, sockets, timers, process control, osls_sleep) are intentionally not registered through this read-only path — see SLOsSupportCatalog.getStateChangingPlannedFunctions and DESIGNATE.md §9; each needs its own explicitly granted capability before exposure. The separate nativeExtensionRegistered checks on each platform facade still return false. Linux procfs/sysfs, netlink, epoll, inotify and cgroups; Windows Win32/IP Helper, SCM/Registry and Winsock; and macOS Mach/Dispatch/IOKit/FSEvents/SystemConfiguration remain separate platform-extension families and are not exposed as registered until their own native binding implementations are added.

Status and execution rules

Build and verification

The C/C++ runtime support package remains buildable independently:

cmake -S lib/os-level-support -B build/lib-os-level-support cmake --build build/lib-os-level-support ctest --test-dir build/lib-os-level-support --output-on-failure

The .sleela catalogue files use the repository's existing SLList source class. The OSLS VM bridge is compiled into the native runtime and can be exercised with make -C impl test-osls-vm; run the full platform build and CMake tests on Linux, Windows and macOS before declaring cross-platform conformance.

Source-level catalogue example

The example at examples/SLOsSupportCatalogExample.sleela constructs the catalogue and platform backend objects, then enumerates the common API, VM bindings and native API lists. The OSLS VM adapter is registered through OP_OSLS_CALL; platform-extension families remain separately gated.

Files 30