WaveOS

Public name for the WCM codebase. Internal filenames, Python modules, and artifact prefixes keep the short wcm prefix.

An experimental operating system where computation, memory, and communication are all waves on a shared physical surface.

---

What is this?

WaveOS is a full OS — processes, windows, files, a shell, apps, a compiler — built on top of a simulated wave-physics substrate instead of Boolean logic gates.

The substrate is a 2D grid of cells governed by the FitzHugh-Nagumo equation (a well-studied model of excitable media, originally from neuroscience). Waves propagate across the grid, interfere, settle into stable states, and decay. WaveOS maps every OS concept onto this physics:

• A process is a region of the grid that oscillates.
• A message is a wave that crosses from one region to another when their oscillation phases align.
• A stored bit is a cell held at one of two stable voltages (like a latch, but made of wave physics instead of transistors).
• A window is a viewport over a region's voltage state.

Python simulates the physics and executes the WaveIL runtime (it plays the role of the chip). On the strict path, shell, input-routing, explorer, and app policy outcomes are owned by WaveIL rather than Python fallbacks.

What does it actually do?

Boot it and you get a desktop with a taskbar, a launcher, a file explorer, a text editor, a clock, and window management (focus, raise, snap, move). You can open files, edit text, navigate directories, and launch apps. It renders at 1080×1920 through a Tkinter window.

All of this is driven by ~4,800 WaveIL instructions across 12 policy packages, compiled from WaveLang (a small language that looks like Rust-lite). App registration is registry-first: installer.py updates a canonical policy registry, and policy_registry.py regenerates the package index, dispatch metadata, opcode aliases, launcher catalog, and generator-owned shell routing from that one source of truth.

Why?

Von Neumann machines move data between separate memory and compute units on a bus. Every operation is a fetch-decode-execute cycle. WaveOS explores what happens when you eliminate that separation — when the medium that stores data is the same medium that computes on it and communicates through it.

In the current simulator, several interesting properties show up:

• Compute scales with activity, not chip area. Quiescent regions cost nothing. At 691K cells, only 5.9% of the grid is computed per tick (sparse frontier). On real analog hardware, inactive cells would draw only leakage current.
• Search is flat-cost. Content-addressable grep over bistable storage runs at ~10 µs per probe regardless of whether there are 64 or 4,096 stored patterns. Peak: 582.7 Mbit/s.
• IPC is physics, not arbitration. Two processes communicate when their oscillation phases align. No bus, no arbiter, no polling.
• Fuzzy matching is free. Wave grep tolerates up to 25% bit corruption and still returns correct results. No fuzzy-matching algorithm — it's intrinsic to the Hamming-distance physics.

Whether these properties transfer to real hardware is the open question. The simulation proves the model works. Hardware would prove the physics.

Quick start

# Boot the desktop (opens a Tkinter window)
.venv/Scripts/python.exe os_production_strict.py

# Run a gate check (headless, ~30s)
.venv/Scripts/python.exe main.py --scenario strict-waveil-first-gate --ticks 200

# Full CI sweep (headless, ~5 min)
.venv/Scripts/python.exe main.py --scenario ci-sweep

Requires Python 3.11+ with NumPy and Tkinter (for GUI mode).

Quick Start - Build a WaveOS App

The shortest path to a new WaveOS app is:

1. Write a WaveLang source file in sdk_apps/.
2. Give it a package id like package "wave.policy.my_app".
3. Install it through installer.py, which updates the canonical registry and regenerates the derived package wiring.
4. Run the registry parity check and the strict ownership gate.

Minimal example:

package "wave.policy.hello"

fn main() {
  let surface = {
    "title": "Hello",
    "glyph_runs": [
      {"row": 12, "col": 10, "text": "HELLO WAVEOS"}
    ]
  };
  app_surface_publish(surface);
}

Install and register it:

.venv/Scripts/python.exe installer.py sdk_apps/hello.wl --kind hello --icon "[H]" --description "Hello App" --domain p03 --name hello --max-instructions 128

Validate the setup:

.venv/Scripts/python.exe policy_registry.py check
.venv/Scripts/python.exe main.py --scenario strict-waveil-first-gate --ticks 200

What the installer now does:

• compiles .wl to .wpk.json
• deploys the package into sdk_apps/system_policy/
• updates sdk_apps/system_policy/policy_registry.json
• regenerates package_index.json, generated/policy_dispatch.json, generated/opcode_aliases.json, and generated/launcher_catalog.json
• rewrites generator-owned shell routing from the registry

What you should not hand-edit for a normal app install:

• sdk_apps/system_policy/generated/*.json
• generator-owned routing in sdk_apps/system_policy/wave.shell.wpk.json
• handwritten Python dispatch tables

For the deeper flow and the full manual path, see docs/README.md and docs/Policy_Registry_ABI_v0.md.

Project structure

wcm.py                  Kernel — assembles substrate, storage, shell, apps
wcm_substrate.py        FHN wave physics, domains, IPC, scheduling
wcm_storage.py          Bistable storage (bits as voltage latches)
wcm_shell.py            Window management, display compositor
wcm_apps.py             App lifecycle, packaging, boot sequence
wcm_il.py               WaveIL virtual machine (~174 opcodes)
wcm_constants.py        Shared constants and data structures
wavelang.py             WaveLang compiler (.wl → .wpk.json)
installer.py            App registration automation
policy_registry.py      Registry generator/validator for package and dispatch metadata
os_production_strict.py Production boot entry ("power button")
main.py                 CLI for scenarios and gates

sdk_apps/               WaveLang source + compiled packages
  system_policy/        12 boot-time policy packages
scenarios/              Test scenarios, benchmarks, quality gates
artifacts/              Gate results as JSON (benchmarked data)
docs/                   Technical reference, ABI specs, roadmaps

Documentation

Doc	What it covers
Technical Reference	Full architecture: layers 1–10, every module, every opcode category
Why WaveOS	Motivation, novel properties, benchmarked results, gate status
Chipset ABI	Hardware transfer contract: primitives, constants, HAL interface
Manufacturing Brief	Hardware readiness assessment
WaveIL Spec	Instruction set format and semantics
Wave ABI	Syscall-level contracts
Capability Policy	Security model: deny-by-default, manifest grants
Display Delta ABI	Sparse display commit protocol
Policy Registry ABI	Active registry-first contract for package, dispatch, launcher, and tick-runtime wiring
Dev Mode	Validation tiers, checkpoint rules

Status

WaveOS is an experimental research prototype. It is not production-ready, and hardware transfer remains a target rather than a validated result.

WaveOS is released as GPL-3.0-only open-source software. Commercial licensing and collaboration inquiries are welcome. If you are considering commercial use or direct derivative work based on this codebase, please begin with direct contact with the author.

Latest completed full CI sweep: 8/12 checks green, 4/12 red.

• Passing: abi, semantic_ownership, python_off, storage_backend, storage_backends, production_strict, hal_boundary, strict_waveil_first
• Red: driver_gate, shell, explorer, waveil_explorer
• Driver KPI currently passes leak, frame cadence, pointer routing, and keyboard routing checks, but fails the activity-floor checks.

The OS still boots into a working desktop, runs apps written in WaveLang, stores files in bistable physics, and keeps the strict ownership path green even while the broader sweep is red.

Known Limits

• The latest full CI sweep is red. Treat the current branch as active prototype work, not a release candidate.
• Hardware implications are not validated. The simulator demonstrates a model and a transfer path, not FPGA, memristor, or manufacturing proof.
• The public API story is ahead of the release hygiene story. Internal filenames and module prefixes still use wcm, and some broader docs still describe transitional architecture debt.
• The app/tooling ecosystem is intentionally small: one compiler, one VM, a small policy package set, and a narrow validation harness.

Useful Feedback

• Reproducible gate failures with the exact command, platform, and artifact path.
• Strict-path ownership regressions where Python retakes policy behavior from WaveIL.
• Registry/runtime drift involving policy_registry.json, generated outputs, or boot/package wiring.
• Clear simulator-vs-hardware framing problems in docs.

See CONTRIBUTING.md for contribution expectations and SECURITY.md for security-reporting posture.