Home /Modules/os-level-support/DESIGNATE.md

DESIGNATE.md

os-level-support/DESIGNATE.md · 666 line(s) · markdown

OS-Level Support Designation

Status: Design inventory and implementation roadmap Target platforms: Linux, Windows 10 and later, and macOS Implementation languages: C ABI with a thin C++ facade; SLeeLa bindings are a separate integration layer Scope: User-mode host services and portable operating-system capabilities

This document designates the common OS-support function surface and the platform-dependent function families that the SLeeLa OS-level-support layer should account for. It is a capability inventory, not a claim that every item is implemented. Each capability is classified as Implemented, Partial, Planned, or Platform-specific candidate.

The portable API should expose stable, OS-neutral names and result types. Platform backends may use native APIs internally. A capability that is unavailable, denied by policy, or unsupported on a particular platform must return an explicit status; it must not silently fabricate a value or weaken host security.

1. Platform and implementation policy

PlatformRequired targetNative implementation family
LinuxSupported distributions with a documented minimum toolchain/kernel baselinePOSIX interfaces, Linux system calls through documented user-mode libraries, procfs/sysfs where available, and libc
WindowsWindows 10 and laterWin32 / Kernel32, Userenv, IP Helper, Winsock, and documented Windows APIs
macOSSupported macOS releases with a documented minimum deployment targetDarwin / POSIX interfaces, SystemConfiguration, sysctl, Mach APIs, and documented Apple frameworks

The implementation must not assume that Linux, Windows, and macOS expose identical metadata. Normalize values where semantics genuinely match; otherwise expose a platform extension or a capability query.

Status definitions

2. Common OS-supported function catalogue

These are the common, OS-neutral function families. The same conceptual operation should be available on all three platforms wherever the host OS permits it.

Function familyDesignated operationsCurrent repository status
Host and system identityDetect OS/platform; retrieve hostname, logged-in user name, current working directory, process ID, system time and monotonic timeImplemented — osls_get_system_info
Process inspectionRetrieve current-process metadata: PID, parent PID where available, thread count, start time, executable path, command line, working directory, state and ownerPartial — osls_get_process_info; current implementation is deliberately limited to the caller's own process
Process enumerationEnumerate processes visible to the caller under the library's documented policyPartial — osls_enumerate_processes returns only the caller's process; system-wide enumeration is not implemented
EnvironmentRead one environment variable; enumerate the current process environmentImplemented — osls_get_environment_value, osls_enumerate_environment
Filesystem metadataQuery file type, size, timestamps, and readable/writable/executable indicatorsImplemented — osls_get_file_info; access indicators are observations, not guarantees that a later operation will succeed
Directory inspectionList directory entry namesImplemented — osls_list_directory
Filesystem operationsOpen, read, write, append, create, truncate, flush, close, copy, move/rename, remove, create/remove directory, inspect links, and query available spacePlanned — add explicit handles, error mapping, permissions and race-safe semantics before exposing these operations
Path handlingNormalize paths, resolve relative paths, join/split components, inspect roots/volumes, and query canonical paths where supportedImplemented — osls_path_normalize, osls_path_join (pure computation), osls_path_resolve (canonical, read-only), osls_get_path_info (normalized/root/absolute/exists)
CPU and machine informationLogical/physical processor counts, architecture, vendor/model, cache-line information, and total/available memoryImplemented — osls_get_cpu_info now populates vendor/model (CPUID on Windows, /proc/cpuinfo on Linux, sysctl on macOS) and cache-line size on all three; osls_get_system_load adds load averages (POSIX; Windows reports -1)
Memory informationTotal, available, used and page-size information; process working-set/resident memory where availableImplemented — osls_get_memory_info, osls_get_available_memory (total/available/used/page-size on Linux/Windows/macOS); per-process working-set remains planned
Time and clockWall-clock time, monotonic time, high-resolution counter, clock frequency/resolution, and UTC/local conversionPartial — system wall-clock and monotonic nanoseconds are returned by osls_get_system_info
Timezone and calendarTimezone identifier/abbreviation, UTC offset, daylight-saving state, local-time conversion, and calendar dataImplemented with portability limits — osls_get_timezone_info; identifier fidelity differs by platform
Network interface inspectionEnumerate interfaces and report names, link state, loopback status, MAC address, IPv4 and IPv6 addressesImplemented — osls_get_network_interfaces; Windows now uses IP Helper GetAdaptersAddresses (names, MAC, IPv4/IPv6, up/loopback) instead of returning OSLS_UNSUPPORTED; POSIX uses getifaddrs
Network configuration inspectionRead DNS resolver configuration, routes, interface addresses, gateways, MTU and interface statisticsPartial — osls_network_resolve performs read-only hostname/service resolution (no connection); routes, gateways, MTU and statistics remain planned
Socket and network I/OCreate/close sockets; bind/listen/accept/connect; send/receive; poll readiness; resolve hostnames; inspect socket endpointsPlanned — portable Winsock/POSIX facade with explicit nonblocking and timeout semantics
Scheduling expressionsValidate five-field cron expressions and calculate the next local-time occurrenceImplemented — osls_cron_validate, osls_cron_next_after; calculation only, not OS schedule installation
Timers and waitingMonotonic timers, deadlines, sleep, waitable events and cancellation primitivesPlanned — distinguish process-local timers from OS-managed persistent schedules
Runtime event hooksRegister/unregister callbacks, emit in-process events, and dispatch event payloadsImplemented — osls_runtime_subscribe, osls_runtime_unsubscribe, osls_runtime_emit; these are library callbacks, not operating-system hooks
Cooperative task queuePost callbacks, run one queued task, and inspect pending task countImplemented — osls_runtime_post, osls_runtime_run_one, osls_runtime_pending; caller pumps the queue
Dynamic module loadingOpen a trusted shared library, verify the declared ABI version, resolve the declared entry point, call it and close itImplemented — sl_native_open, sl_native_run_module, sl_native_close; native code runs in-process and is not sandboxed
OS and runtime capabilitiesQuery whether an operation is available, permitted, and supported by the current backendImplemented — osls_get_capabilities and osls_get_runtime_info (backend, ABI version, registered operation count, capability mask), separate from attempting the operation
Error and status reportingStable portable status codes plus native error detail for diagnosticsImplemented — base status enums plus osls_get_native_error (native errno/GetLastError code and message); per-operation threading of native detail remains a refinement

3. Common cross-platform API

This is the shared SLeeLa OS-level-support API intended to present one stable C interface across Linux, Windows, and macOS. Platform backends translate these operations to the appropriate native functions. The names below are portable SLeeLa API names, not Win32, Linux, or Darwin symbols.

3.1 Existing common C API — alphabetical

These functions are declared in the current public headers. Their implementation status is described in the common catalogue and must be checked per platform.

3.2 Existing common runtime API — alphabetical

These functions are declared in runtime/osls_runtime.h. They are library-managed, in-process callbacks and cooperative task dispatch; they are not OS hooks, threads, or background workers.

3.3 Existing shared-module API — alphabetical

These functions are declared in loader/native_loader.h. They provide shared-library loading and ABI entry-point handling. Loading a module executes native code in the current process and does not create a sandbox.

3.4 Planned common API extensions — alphabetical

The following names are proposed portable API additions for the common capability catalogue. They are design designations, not current exported symbols. Final signatures, ownership rules, buffer conventions, and ABI versioning must be specified before implementation.

API consistency rules:

  1. Use the osls_ prefix for portable OS-support functions; keep osls_runtime_ for runtime queue/event operations and sl_native_ for native module loading.
  2. Keep common API names and result semantics identical on all three platforms. Platform-only capabilities must use an explicitly platform-qualified extension namespace.
  3. Use UTF-8 strings at the public C ABI boundary; perform native encoding conversion inside the backend.
  4. Use opaque handles for open files, sockets, and timers. Define whether each handle is thread-safe and which function releases it.
  5. Distinguish invalid arguments, not found, unsupported, access denied, buffer too small, timeout, and native system failure. Preserve the native error separately from the portable status.
  6. Do not expose platform-specific structs, handles, constants, or calling conventions in the common header.
  7. Do not finalize duplicate aliases such as osls_create_directory and osls_make_directory; choose one canonical exported name before freezing the ABI.
  8. Mark each function as implemented, partial, or planned in the implementation matrix, and test it on Linux, Windows 10+, and macOS.

4. Linux-specific function families

Linux-specific functions belong in a Linux backend or a clearly named Linux extension. They must not leak Linux-only types into the common C ABI.

Function familyLinux capabilities to supportDesignation
Kernel and distribution identityKernel release/version, machine architecture, distribution identity/version when reliably discoverable, boot ID where permittedPlatform-specific candidate
Process metadataRead permitted /proc process metadata, status, command line, executable link, thread count, start time and resource countersPlatform-specific candidate; current common process API is self-only
Process resource limitsQuery current-process limits and accounting data using documented interfacesPlatform-specific candidate
Memory and system loadsysinfo, /proc/meminfo, load averages, swap totals and page sizePlatform-specific candidate
CPU topologyCPU model/vendor, online CPUs, physical/core/thread topology, cache information and CPU frequency when exposedPlatform-specific candidate
Filesystem and mountsMount table, filesystem type, mount flags, disk capacity, inode capacity and filesystem statisticsPlatform-specific candidate
Device and hardware metadataRead-only device enumeration and selected sysfs metadata, subject to permissionsPlatform-specific candidate
NetworkInterface flags, link-layer addresses, IPv4/IPv6 addresses, routes, neighbors, DNS configuration, MTU and interface countersPlatform-specific candidate
Event notificationinotify-based filesystem change notifications; poll/epoll readiness integrationPlatform-specific candidate
Process and system eventsRead-only event sources where available; no ptrace-based process control in the common support layerPlatform-specific candidate
Resource controlsQuery cgroup membership and readable CPU/memory/pid limits; report namespace/container context when availablePlatform-specific candidate
Service and session informationRead-only systemd/service-manager and login-session state when the relevant service interface is availablePlatform-specific candidate
Clock and power metadataClock source/resolution and available power/battery metadata where exposedPlatform-specific candidate

Linux implementation notes:

5. Windows-specific function families

Windows-specific functions belong in a Windows backend or a clearly named Windows extension. Use documented Win32 APIs and preserve Windows access-control behavior.

Function familyWindows capabilities to supportDesignation
OS identityProduct name/edition, version/build, architecture, computer name and boot/session information using supported version APIsPlatform-specific candidate
Process metadataCurrent-process image path, command line, parent PID and permitted process countersPartial in current self-only API; extensions planned
Process resource dataCurrent-process working set, private bytes, handles, thread count and CPU accounting when permittedPlatform-specific candidate
CPU and memoryProcessor topology, logical/physical core counts, cache data, page size, physical/available memory and processor architecturePartial — current CPU API does not yet populate all fields
Filesystem and volumesVolume enumeration, filesystem type, volume capacity, free space, file attributes, reparse-point information and file timestampsPlatform-specific candidate
Directory change notificationReadDirectoryChangesW-based change notificationsPlatform-specific candidate
NetworkIP Helper interface/address/route/statistics APIs, DNS configuration and Winsock socket informationPartial — current interface enumeration is unsupported on Windows
Event and wait primitivesWaitable events, timers, synchronization objects and completion-port readinessPlatform-specific candidate
ServicesRead-only Service Control Manager queries for service state and configuration permitted to the callerPlatform-specific candidate
Registry inspectionExplicit, read-only key/value query with registry-view and access-right handlingPlatform-specific candidate; never silently write or alter policy
User and session metadataCurrent user identity, session information and selected profile pathsPlatform-specific candidate
Power and batteryPower status, battery presence/charge and supported power-source metadataPlatform-specific candidate
Security contextQuery current token identity, groups and enabled privileges for diagnostic display onlyPlatform-specific candidate; never enable privileges or use the result as authorization

Windows implementation notes:

6. macOS-specific function families

macOS-specific functions belong in a Darwin/macOS backend or a clearly named macOS extension. Prefer documented Apple APIs and respect privacy/TCC and sandbox restrictions.

Function familymacOS capabilities to supportDesignation
OS identitymacOS product/version/build, Darwin kernel version, architecture and hardware modelPlatform-specific candidate
Process metadataCurrent-process executable path, parent PID, thread and resource information where permittedPartial in current self-only API; extensions planned
CPU and memoryLogical/physical CPU counts, CPU model, memory size, page size and available-memory statisticsPartial — sysctl-backed subset exists
System configurationRead-only sysctl values for documented hardware and kernel metadataPlatform-specific candidate
Filesystem and volumesMounted volumes, filesystem type, volume capacity, available space, file attributes and resource identifiersPlatform-specific candidate
Filesystem eventsFSEvents and vnode/kqueue notifications, with explicit scope and lifecyclePlatform-specific candidate
NetworkInterface and link-layer metadata, addresses, routes, DNS configuration, service order and network-change notificationsPartial — current common interface enumeration uses POSIX interfaces
System and user servicesRead-only launchd service/job state where supported by documented interfaces and permissionsPlatform-specific candidate
Power and batteryI/O Kit power-source and battery metadata where availablePlatform-specific candidate
Hardware metadataRead-only model, architecture, selected device and power metadata through documented system interfacesPlatform-specific candidate
Privacy and sandbox stateReport relevant permission-denied/sandbox-limited conditions; do not attempt to bypass TCC or sandbox policyPlatform-specific candidate
Clock and notificationsMach monotonic clock and supported dispatch/timer facilitiesPartial — Mach monotonic time is used by the current system-info implementation

macOS implementation notes:

7. Platform capability comparison

The following matrix describes the intended backend coverage, not a claim that every backend is complete today.

CapabilityLinuxWindowsmacOS
Host identity and clocksPOSIX + Linux metadataWin32POSIX + Mach
Environment and current directoryPOSIX/libcCRT + Win32POSIX/libc
Current-process inspectionprocfs + POSIXWin32 process APIsprocfs-style APIs are not assumed; Darwin process APIs
File metadata and directory listingPOSIXWin32POSIX
CPU and memorysysconf/sysinfo/procfs/sysfsWin32 system/memory APIssysctl/Mach
Timezonelibc/timezone databaseCRT/Windows timezone APIslibc/ICU or supported system configuration APIs
Network interfacesgetifaddrs/netlinkIP Helpergetifaddrs/SystemConfiguration
Network socketsPOSIX socketsWinsockBSD sockets
Filesystem notificationsinotifyReadDirectoryChangesWFSEvents/kqueue
System/service inspectionsystemd or available service managerService Control Managerlaunchd-supported interfaces
Hardware/power metadatasysfs and available system interfacespower APIsI/O Kit
Dynamic library loadingdlopen/dlsymLoadLibrary/GetProcAddressdlopen/dlsym
Local timers/eventsPOSIX facilitieswaitable objects/timersMach/dispatch/POSIX facilities

A cell identifies a likely native implementation family. It does not promise identical output, identical permissions, or identical semantics across operating systems.

8. C ABI and C++ facade requirements

  1. Keep the C ABI authoritative and usable from C and C++.
  2. Use fixed-width integer types for ABI-visible numeric fields.
  3. Use explicit caller-provided buffer sizes or opaque handles; never return pointers to temporary internal storage.
  4. Define ownership and lifetime for every returned buffer, handle, callback payload and native resource.
  5. Return a stable OSLS status and, where useful, a separate native error code.
  6. Provide capability discovery for optional functions and distinguish unsupported from access denied.
  7. Keep the C++ facade thin: RAII, value types, strings/vectors and safe handle ownership; do not create a second incompatible semantic API.
  8. Use UTF-8 at the portable API boundary. Convert to/from native encodings explicitly.
  9. Define time units, epoch, monotonic-clock semantics, path rules, and whether timestamps represent creation, metadata change, or modification.
  10. Document whether each function is read-only, process-local, system-wide, blocking, asynchronous, or permission-sensitive.

9. Security and authority boundaries

The OS-level-support library is a user-mode portability layer. Its functions report host state or perform explicitly requested, ordinary user-mode operations. They do not confer authority.

The following are out of scope for this library and must not be added as implied consequences of a successful metadata or trust check:

Any future operation that writes files, changes settings, starts a process, or modifies a service must be separately specified, explicitly invoked by the caller, permission-checked by the OS, and documented as a state-changing operation. It must not be hidden behind a read/query API.

10. Implementation priorities

  1. Complete and correct the existing common API: (revision 1.1) Windows network-interface enumeration is now implemented via IP Helper; CPU vendor/model and cache-line fields are now populated on all three platforms; the Windows timezone identifier now uses the real time-zone key name. Remaining: improve process metadata consistency and validate timestamp semantics across platforms.
  2. Add capability and error reporting: expose backend capabilities and native diagnostic codes consistently.
  3. Complete common read-only inspection: dedicated memory, path, volume, mount, route, DNS, socket and interface-statistics APIs.
  4. Add event facilities: filesystem notifications and portable wait/timer abstractions with OS-specific backends.
  5. Add carefully scoped platform extensions: Linux procfs/sysfs/cgroup/service metadata; Windows volume/service/registry-read/power metadata; macOS volume/FSEvents/launchd/power metadata.
  6. Add tests on all three operating systems: compile-time coverage, runtime tests, unavailable-permission tests, Unicode paths, large buffers, missing facilities, and error mapping.
  7. Publish an implementation matrix: each function must identify its header, backend source, supported platforms, tests, permission requirements and current status before being described as complete.

11. Current public API reference

The current root C API is declared in osls.h and implemented across osls.c and osls_extended.c:

Revision 1.1 adds the following read-only inspection functions, all registered through OP_OSLS_CALL operation IDs 12..24 under the same host-read capability:

The remaining planned functions (file open/read/write/close, copy/move/remove, directory create/remove, sockets, timers, and osls_sleep) are state-changing or handle/stream operations. By the authority boundary in section 9 they are deliberately not registered through the read-only OP_OSLS_CALL path; each must be specified with its own explicitly granted capability before it is exposed, and must never be reachable under the default host-read capability.

The runtime callback/task API is declared in runtime/osls_runtime.h. The native shared-module API is declared in loader/native_loader.h. Their presence does not imply sandboxing, OS syscall interception, persistent scheduling, or process creation.

12. Alphabetical native operating-system function index

This index names native functions and documented system interfaces that may implement the capability families above. Names are grouped by operating system and sorted alphabetically within each group. It is an implementation reference, not a promise that every function is currently called by SLeeLa or is available on every supported OS release. Prefer documented, user-mode APIs; check availability, permissions, and return status at runtime.

12.1 Windows — Win32 and documented system APIs

The following Win32 and Windows API names are listed alphabetically. Related API families are included where they are relevant to the designated support surface.

Additional Windows API families (alphabetical):

12.2 Linux — POSIX, libc, and Linux system interfaces

The following function names are listed alphabetically. Some are libc/POSIX interfaces and some are Linux-specific interfaces or system calls. Prefer libc wrappers over issuing raw system calls directly.

Additional Linux interfaces (alphabetical):

12.3 macOS — Darwin, POSIX, Mach, and Apple system APIs

The following function names are listed alphabetically. Availability and permissions vary by macOS release, sandbox profile and privacy authorization.

Additional macOS frameworks and interfaces (alphabetical):

Index maintenance rule: Keep each operating-system list alphabetized whenever entries are added. Distinguish function names from API families and pseudo-filesystem interfaces; identify any state-changing call explicitly, and do not describe a candidate API as implemented until the corresponding backend and tests exist.

13. SLeeLa source catalogue and VM element model

The SLeeLa source representation for this inventory lives in lib/os-level-support/. It separates capability vocabulary, reusable element descriptors, the existing VM system-call bridge, the richer portable C ABI, and the three platform symbol lists.

SLeeLa source elementResponsibility
SLOsSupportCatalog.sleelaCanonical common capability groups and portable API/function catalogues
SLOsSupportElement.sleelaOne binding descriptor: group, VM element/opcode, portable symbol, native symbol, backend, effect, status, result and arity
SLOsSupportVMBridge.sleelaVM dispatch vocabulary, status and marshalling terms, and the current opcode map
SLOsSupportVMElements.sleelaFactory methods for the 21 existing VM OS-call elements
SLOsSupportOSLSElements.sleelaFactory methods for the 12 current osls_* C ABI elements
SLOsSupportLinux.sleelaLinux groups and alphabetized POSIX/Linux native symbol catalogue
SLOsSupportWindows.sleelaWindows groups and alphabetized Win32/Winsock native symbol catalogue
SLOsSupportMacOS.sleelamacOS groups and alphabetized Darwin/POSIX/Mach native symbol catalogue
examples/SLOsSupportCatalogExample.sleelaSource example enumerating groups, VM mappings and OS-specific catalogues

13.1 Canonical grouping terms

The shared catalogue uses these semantic group identifiers:

The platform classes add qualified group terms such as LinuxCPUTopology, WindowsServices, and MacOSFilesystemEvents. Use the shared term when the operation is semantically portable; use a qualified term only for a genuine platform-specific facility.

13.2 Existing VM path and registered osls adapter

The current VM already exposes the OS system-call family through SleelaVMSystemCallBridge.sleela, the OP_OS_* opcodes 103–123, and the native host implementation in impl/core/sleela_os.h / impl/core/sleela_os.c. The SLeeLa source element factories map these VM operations to their current slos_* backend symbols and mark them implemented.

The root library's osls_* inspection ABI is now registered through os-level-support/osls_vm_bridge.c and append-only opcode OP_OSLS_CALL (155). Twelve stable operation IDs bind the declared APIs through a callable native function-pointer registry. Each entry includes the native symbol, typed argument vector, JSON UTF-8 result type, and required host-read capability. The compiler lowers the osls... built-ins to that opcode; the VM checks each operation's arity and value types, then returns a bounded JSON String containing native status and result. Raw pointers and C record layouts do not cross into VM values. The CMake package and SLeeLa VM Makefile compile the adapter and platform implementation. CMake's osls_vm_bridge_test and make -C impl test-osls-vm exercise the native registry and VM dispatch respectively. Platform-specific extension catalogues remain separate and unregistered until their own native bindings and cross-platform tests are added.

All element effects must remain explicit: read-only query, read-only enumeration, process-local operation, blocking operation, or state-changing operation. Permission decisions remain with the host OS. Existing process launch/termination, environment mutation, directory changes and filesystem mutation must not be silently triggered by catalogue lookup or element construction.


Designation: Linux, Windows, and macOS are the required target platforms. Common behavior belongs in the portable API; genuine OS differences belong in platform backends or explicitly named extensions. All status labels in this document must be updated as implementation and cross-platform tests are completed.