# Programming Languages

capOS currently supports native Rust programs that are written for the capOS
userspace runtime. Other languages are design tracks, not implemented platform
support. The main rule is simple: a language runtime may expose familiar APIs,
but authority still comes from the process CapSet and typed capability calls.

## Current Support

| Language or runtime | Status | Path |
| --- | --- | --- |
| Rust, capOS-native | Implemented baseline | `#![no_std]`, `alloc`, `capos-rt`, static ELF, `x86_64-unknown-capos` |
| Rust `std` | Not implemented | Future Rust standard-library or adapter work over capabilities |
| C | Future design | Static `libcapos` startup, ring calls, CapSet, and generated C-facing wrappers |
| C++ | Future experiment | Depends on C startup, ABI choices, allocator, exceptions/RTTI policy, and a useful freestanding subset |
| Go | Future design | Custom `GOOS=capos` or a narrower WASI path for CPU-bound tools such as CUE |
| Python | Future design | Native CPython or MicroPython through a POSIX-style adapter; WASI/Emscripten for sandboxed or compute-only use |
| Lua | Future design | Capability-scoped runner with curated libraries and explicit grants |
| JavaScript / TypeScript | Future design | QuickJS-style native runner or WASI-hosted engine; not a browser JS shell |
| WASI / WebAssembly | Future design | Host imports backed by capabilities; useful for sandboxed code and portable tools |
| POSIX-shaped software | Future design | Compatibility adapter over explicit file, directory, socket, stdio, timer, process, and namespace caps |

## Native Rust Today

The implemented path is Rust without the standard library. Programs use
`core` and may use `alloc` types such as `Vec`, `String`, `Box`, and
`BTreeMap` because `capos-rt` installs a userspace allocator. They do not get
`std::fs`, `std::net`, `std::thread`, `println!`, environment variables,
process arguments, or a libc syscall table.

`capos-rt` owns the repeated runtime machinery:

- the `_start` entry point and `capos_rt_main` handoff;
- fixed heap initialization;
- panic output through an emergency Console path when available;
- raw `exit` and `cap_enter` syscall wrappers;
- CapSet lookup and interface-id checks;
- a single-owner ring client;
- typed clients for implemented kernel and service capabilities;
- result-cap adoption and queued local release.

Native programs should keep ordinary Rust business logic in normal modules and
push OS interaction to typed capOS clients. That keeps pure logic host-testable
while making authority visible at capability lookup and child-spawn sites.

## Why `std` Is Different

Rust `std` is not just "more Rust." It is an operating-system binding. It
expects an implementation of filesystem, networking, threads, time, standard
I/O, process, environment, synchronization, and platform error APIs. On Linux
those calls are ambient: a process can ask the kernel to open a path or create
a socket and the kernel consults global process credentials.

capOS does not have that ambient authority model. A future Rust `std` path must
choose how each `std` feature gets authority:

| `std` area | capOS authority source |
| --- | --- |
| `std::io::{stdin, stdout, stderr}` | `StdIO`, `Console`, or `TerminalSession` caps |
| `std::fs` | scoped `Directory`, `File`, `Store`, or `Namespace` caps |
| `std::net` | socket or listener caps minted by a network service |
| `std::thread` | `ThreadSpawner`, `ThreadControl`, `ThreadHandle`, and ParkSpace support |
| `std::time` | `Timer` and future wall-clock caps |
| process spawn and wait | `ProcessSpawner`, `RestrictedLauncher`, and `ProcessHandle` caps |
| `std::env` and current directory | synthetic runtime state backed by manifest or namespace caps |

That mapping can be implemented as a capOS `std` backend, a Rust compatibility
crate, or a POSIX-style adapter. The project has not selected one shared ABI
for all language runtimes.

## Compatibility Terms

Use these terms instead of the vague phrase "compatibility layer":

- **Native runtime adapter**: language-specific runtime glue that talks to
  capOS capabilities directly. `capos-rt` is the implemented Rust example;
  `GOOS=capos` would be the Go example.
- **Capability-native bindings**: generated or handwritten bindings that expose
  Cap'n Proto interfaces as language-level APIs without POSIX names.
- **POSIX compatibility adapter**: a libc or library surface that translates
  `open`, `read`, `write`, `socket`, `poll`, `clock_gettime`, and similar APIs
  into operations on granted capabilities.
- **WASI host adapter**: a WebAssembly host implementation whose imports are
  backed by granted capOS capabilities.

The adapter may make code look familiar, but it cannot create authority. A
process without a namespace cap still cannot open a file. A process without a
network cap still cannot create a socket. A process without a launcher or
spawner cap still cannot create children.

## Language Tracks

### Rust

Rust is the only implemented userspace language. The current target is
`targets/x86_64-unknown-capos.json`, which exposes `target_os = "capos"` while
keeping the booted userspace baseline `no_std`, static, and `panic = "abort"`.
`init`, `demos`, `shell`, and the `capos-rt` smoke binary build through this
custom target.

Open work before broader Rust support:

- generated clients after the schema surface stabilizes;
- runtime ParkSpace clients and multi-threaded ring demultiplexing;
- a decision on Rust `std` over native capabilities versus a POSIX adapter;
- package/build conventions for out-of-tree capOS Rust programs.

### C and C++

C support is a future `libcapos` track, not implemented. The intended shape is
a static library that owns startup, CapSet access, ring calls, and generated
wrappers over Cap'n Proto interfaces. That is enough for small C services and
for bringing up runtimes such as CPython, MicroPython, Lua, and QuickJS.

C++ should wait until the C substrate exists and the project decides its C++
ABI policy: exceptions, RTTI, TLS, allocation, unwind behavior, and standard
library scope. A freestanding container/arena subset is plausible earlier than
full hosted C++.

### Go

Go is a dedicated future design because its runtime is close to a userspace
operating system. A native `GOOS=capos` port needs virtual memory reservation
and commitment, TLS setup, OS-thread creation, park/wake, monotonic time,
debug output, process exit, and eventually network polling.

The current kernel/runtime substrate already proves useful pieces:
`VirtualMemory`, `Timer`, `ThreadControl`, `ThreadSpawner`, `ThreadHandle`,
and private ParkSpace wait/wake exist at the capOS level. The missing work is
the Go runtime port and the runtime-side integration contract, not a new
ambient syscall namespace.

Go through WASI may be sufficient for CPU-bound tools such as CUE evaluation,
but native `GOOS=capos` remains the path for Go network services and full
runtime behavior.

### Python

Python is not currently supported on booted capOS. The practical paths are:

- **Native CPython through a POSIX compatibility adapter.** This depends on the
  C/libc substrate plus file, stdio, timer, networking, and process adapters.
  It is the likely path for trusted system scripts, configuration tooling, and
  Python programs that need capOS networking or storage.
- **MicroPython through the same native C substrate.** This is a smaller early
  scripting option with less runtime surface than CPython.
- **WASI or Emscripten-hosted Python.** This is useful for sandboxed or
  compute-oriented Python. It still runs a Python interpreter; WebAssembly is
  the sandbox/host ABI, not a way to avoid Python runtime work.

Current upstream CPython support is relevant but not sufficient by itself:
[PEP 11](https://peps.python.org/pep-0011/) lists
`wasm32-unknown-wasip1` as a Tier 2 CPython platform and
`wasm32-unknown-emscripten` as Tier 3, while
[PEP 776](https://peps.python.org/pep-0776/) records Emscripten support for
Python 3.14. Those targets help the WASM path. They do not provide native capOS
file, socket, thread, or capability bindings.

### Lua

Lua is a future capability-scoped scripting runner. The target is not a POSIX
Lua shell. A `capos-lua` process should receive an exact CapSet, load curated
standard libraries, expose capabilities as unforgeable host userdata, deny raw
CapIds, and flush owned handles at script exit.

Upstream PUC Lua is a small C implementation, so the native path waits on the
C/libcapos substrate. A pure-Rust Lua-like implementation could prove host API
shape earlier, but it would be an implementation bootstrap rather than a
promise of PUC Lua compatibility.

### JavaScript and TypeScript

JavaScript support means running an engine as an ordinary capOS process. A
small QuickJS-style runner is the plausible early native path once C support
exists. V8 or SpiderMonkey are much larger C++ runtime ports and should be
treated as later experiments. TypeScript would normally compile before
execution; capOS should not make a TypeScript compiler part of the kernel or
base runtime.

### WASI and Browser WebAssembly

WASI support is a host-runtime track: the host imports become capability
calls. This is a good fit for code that is already designed around explicit
imports and sandboxed execution. It is not a replacement for native runtime
ports when the language expects OS threads, signals, sockets, memory mapping,
or a large POSIX surface.

The browser/WebAssembly proposal is separate. It explores running capOS concepts
in a browser using worker-per-process isolation and SharedArrayBuffer-backed
rings. It is a teaching and demo target, not current native userspace language
support.

## Proposal Map

- [Userspace Runtime](architecture/userspace-runtime.md) documents the current
  `capos-rt` implementation.
- [Userspace Binaries](proposals/userspace-binaries-proposal.md) owns the
  native binary, language, POSIX-adapter, and WASI roadmap.
- [Go Runtime](proposals/go-runtime-proposal.md) owns the native Go plan.
- [Go VirtualMemory Contract](backlog/go-virtual-memory-contract.md) freezes
  the allocator-facing memory contract needed by Go-style runtimes.
- [Lua Scripting](proposals/lua-scripting-proposal.md) owns the Lua runner
  design.
- [Shell](proposals/shell-proposal.md) distinguishes native shell behavior from
  POSIX shell compatibility.
- [Storage and Naming](proposals/storage-and-naming-proposal.md) defines the
  `Directory`, `File`, `Store`, and `Namespace` surfaces that future POSIX and
  language runtimes will consume.
- [Browser/WASM](proposals/browser-wasm-proposal.md) owns the browser-hosted
  WebAssembly experiment.
- [LLVM Target](research/llvm-target.md) records target-triple, Rust `std`,
  Go, C, TLS, and ABI grounding. The actual `docs/research/` contents were
  listed before this page cited the file.

## Validation

Current language-runtime validation is Rust-only:

- `tools/check-userspace-runtime-surface.sh` verifies that `capos-rt` owns
  `_start`, panic handling, allocator setup, raw syscalls, and entry macros.
- `make capos-rt-check`, `make init-capos-build`, `make demos-capos-build`,
  `make shell-capos-build`, and `make capos-rt-capos-build` build the booted
  userspace artifacts against the capOS custom target.
- `make run-smoke`, `make run-spawn`, `make run-shell`, and
  `make run-terminal` exercise the runtime surface through QEMU.

No page should claim support for Python, Go, Lua, C, C++, JavaScript, WASI, or
Rust `std` until there is a booted artifact and a validation target for that
runtime.