Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Project Structure & Module Organization

InferNode is a mixed C, Limbo, shell, and Go repository. Core runtime and kernel code lives in `libinterp/`, `emu/port/`, and `libsec/`. Limbo applications and libraries live under `appl/`, with notable areas in `appl/cmd/`, `appl/veltro/`, and `appl/xenith/`. Interface definitions belong in `module/*.m`. Tests are under `tests/`, with emulator tests named `*_test.b` and host-side shell tests in `tests/host/*_test.sh`. Supporting material lives in `docs/`, `formal-verification/`, and `tools/godis/`.
InferNode is a mixed C, Limbo, and shell repository — application code is written in Limbo, never in other languages. Core runtime and kernel code lives in `libinterp/`, `emu/port/`, and `libsec/`. Limbo applications and libraries live under `appl/`, with notable areas in `appl/cmd/`, `appl/veltro/`, and `appl/xenith/`. Interface definitions belong in `module/*.m`. Tests are under `tests/`, with emulator tests named `*_test.b` and host-side shell tests in `tests/host/*_test.sh`. Supporting material lives in `docs/`, `formal-verification/`, and `tools/`.

## Design Principles

Expand Down
12 changes: 0 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,17 +113,6 @@ Windows support works (headless + SDL3 GUI) but needs polish:
See [docs/WINDOWS-BUILD.md](docs/WINDOWS-BUILD.md) and
`build-windows-amd64.ps1`.

### GoDis Compiler

The Go-to-Dis compiler (`tools/godis/`) compiles Go source to Dis bytecode.
It's preliminary — 190+ tests passing — and a great area for compiler
enthusiasts:

- Expanding Go language feature coverage
- Improving Dis bytecode generation
- Adding optimization passes
- Test coverage for edge cases

### Platform Testing

We ship on Linux (x86-64, ARM64), macOS (ARM64), and Windows (x86-64).
Expand Down Expand Up @@ -307,7 +296,6 @@ CI will automatically run:
| `appl/lib/` | Limbo | Libraries (styx, styxservers, JSON, TLS, etc.) |
| `module/` | Limbo | Interface definitions (like header files) |
| `formal-verification/` | TLA+/SPIN/CBMC | Security proofs |
| `tools/godis/` | Go | Go-to-Dis compiler |

### The Limbo Language

Expand Down
18 changes: 9 additions & 9 deletions appl/xenith/IDEAS.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,25 +267,25 @@ HTTP as filesystem via 9P. Mount web9p to expose HTTP operations as files:

```sh
# Mount web9p
web9p /n/web
web9p /mnt/web

# Simple GET request
echo 'https://example.com' > /n/web/url
cat /n/web/result
echo 'https://example.com' > /mnt/web/url
cat /mnt/web/result

# POST request
echo 'https://api.example.com/data' > /n/web/url
echo 'POST' > /n/web/method
echo 'body content here' > /n/web/body
cat /n/web/result
echo 'https://api.example.com/data' > /mnt/web/url
echo 'POST' > /mnt/web/method
echo 'body content here' > /mnt/web/body
cat /mnt/web/result

# Check status
cat /n/web/status
cat /mnt/web/status
```

**Filesystem structure:**
```
/n/web/
/mnt/web/
├── url # (w) write URL to fetch
├── method # (rw) GET or POST (default: GET)
├── body # (rw) POST body content
Expand Down
76 changes: 53 additions & 23 deletions docs/9p-data-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,36 @@ space-separated. Records are one per line. Complex structures
are decomposed into the directory hierarchy.


## Where to mount it

Before the data format comes the mount point, and the rule is
about schema authorship, not data location:

**A tree your program synthesizes — you author the schema —
mounts under `/mnt/<app>`, even when the backing data is remote.**
`webfs` serves remote HTTP yet lives at `/mnt/web`, because *it*
invents the `ctl`/`uri`/`body` schema. Every example in this
document is an app-authored tree, so every example mounts under
`/mnt`.

**A foreign tree imported intact — the schema is theirs — mounts
under `/n/<source>`, named for its source.** `/n/local` (the host
filesystem), a remote peer's exported root. A remote LLM does
*not* belong here: you are not importing a peer's tree to live as
`/n/<peer>`, you are populating *your* `/mnt/llm` from it.
Locality is not placement — it is just how the name gets
populated.

The convention is security work, not cosmetics: `/mnt` is ours to
subdivide, so a sub-agent can be granted exactly
`/mnt/<app>/<sub>` and nothing else, while `/n` remains a small,
vetted import allowlist. A few older trees predate the convention (migrations tracked as INFR-400..403)
(`/n/wallet`, `/n/git`); do not copy them for new work. The full
argument, the decision checklist, and the reference tree are in
[NAMESPACE-LAYOUT.md](NAMESPACE-LAYOUT.md) — read it before
choosing any mount point.


## Why Not JSON

JSON is the default instinct for structured data. It is wrong
Expand All @@ -26,7 +56,7 @@ It is a design principle. Every layer of unnecessary syntax is a
layer of unnecessary complexity in every tool that touches the data.

**Clarity.** Text lines are human-readable at every point in the
system. `cat /n/sensors/temperature` shows a number. `cat /n/alerts`
system. `cat /mnt/sensors/temperature` shows a number. `cat /mnt/alerts`
shows one alert per line. There is nothing to decode, no structure
to navigate, no keys to look up. The data is right there. This
matters for debugging, for auditing, for understanding what a
Expand All @@ -40,8 +70,8 @@ server emits one record per line, the full power of this ecosystem
is immediately available.

```
cat /n/sensors/readings | grep temperature | wc -l
cat /n/fleet/vehicles | awk '{print $1, $4}' | sort
cat /mnt/sensors/readings | grep temperature | wc -l
cat /mnt/fleet/vehicles | awk '{print $1, $4}' | sort
```

JSON breaks this. A JSON array is not a sequence of lines — it is
Expand Down Expand Up @@ -100,23 +130,23 @@ optionally followed by a newline.

Sensor network:
```
/n/sensors/temperature → 22.5
/n/sensors/humidity → 0.65
/n/sensors/status → normal
/mnt/sensors/temperature → 22.5
/mnt/sensors/humidity → 0.65
/mnt/sensors/status → normal
```

Fleet tracking:
```
/n/fleet/vehicles/truck-7/lat → 37.7749
/n/fleet/vehicles/truck-7/lon → -122.4194
/n/fleet/vehicles/truck-7/speed → 65.2
/mnt/fleet/vehicles/truck-7/lat → 37.7749
/mnt/fleet/vehicles/truck-7/lon → -122.4194
/mnt/fleet/vehicles/truck-7/speed → 65.2
```

Trading system:
```
/n/portfolio/cash → 125000.00
/n/portfolio/total_value → 1250000.50
/n/portfolio/defense/status → normal
/mnt/portfolio/cash → 125000.00
/mnt/portfolio/total_value → 1250000.50
/mnt/portfolio/defense/status → normal
```

This is the most Plan 9 pattern. The directory hierarchy is the
Expand All @@ -131,23 +161,23 @@ separated by spaces.

Geospatial observations:
```
/n/observations:
/mnt/observations:
sta-001 37.7749 -122.4194 22.5 0.65 clear 2025-02-15T14:32:00Z
sta-002 34.0522 -118.2437 28.1 0.42 clear 2025-02-15T14:32:00Z
sta-003 40.7128 -74.0060 -2.3 0.78 snow 2025-02-15T14:32:00Z
```

Network events:
```
/n/firewall/log:
/mnt/firewall/log:
a]1e8400 10.0.1.15 10.0.2.30 443 allow 2025-02-15T14:32:00Z
b72e8401 192.168.1.5 10.0.1.15 22 deny 2025-02-15T14:33:12Z
c83e8402 10.0.1.20 8.8.8.8 53 allow 2025-02-15T14:33:15Z
```

Trading signals:
```
/n/signals:
/mnt/signals:
550e8400 AAPL long 0.85 sentiment 2025-02-15T14:32:00Z
660e8401 TSLA short 0.72 technical 2025-02-15T14:33:00Z
```
Expand Down Expand Up @@ -189,14 +219,14 @@ content is the value.

Wrong:
```
/n/sensors/station-1 → {"temperature": 22.5, "humidity": 0.65, "status": "normal"}
/mnt/sensors/station-1 → {"temperature": 22.5, "humidity": 0.65, "status": "normal"}
```

Right:
```
/n/sensors/station-1/temperature → 22.5
/n/sensors/station-1/humidity → 0.65
/n/sensors/station-1/status → normal
/mnt/sensors/station-1/temperature → 22.5
/mnt/sensors/station-1/humidity → 0.65
/mnt/sensors/station-1/status → normal
```

If the values are logically grouped, use a subdirectory. The
Expand All @@ -208,7 +238,7 @@ Simple lists (identifiers, labels, available resources) are one
item per line.

```
/n/fleet/drivers:
/mnt/fleet/drivers:
Alice Chen
Bob Martinez
Carol Okafor
Expand All @@ -227,9 +257,9 @@ Files that accept commands (not just data) follow the Plan 9
`ctl` convention. Commands are text strings written to the file.

```
echo alarm > /n/sensors/station-1/status
echo 30 > /n/sensors/station-1/poll_interval
echo rebalance > /n/portfolio/ctl
echo alarm > /mnt/sensors/station-1/status
echo 30 > /mnt/sensors/station-1/poll_interval
echo rebalance > /mnt/portfolio/ctl
```

### Writable data files
Expand Down
7 changes: 4 additions & 3 deletions docs/DESIGN-PRINCIPLES.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ and every existing tool already speaks it.)

**The namespace is the schema.** The directory hierarchy carries
the structure that other systems put into JSON objects, schemas,
and API documentation. `/n/sensors/station-1/temperature`
and API documentation. `/mnt/sensors/station-1/temperature`
containing `22.5` needs no parser and no spec. Design the tree
and you have designed the interface.

Expand Down Expand Up @@ -191,8 +191,9 @@ foreign trees imported intact, named by their source
(`/n/local`, a remote peer's root). The full argument, and why
the convention is itself security work, is in
[NAMESPACE-LAYOUT.md](NAMESPACE-LAYOUT.md). A few older trees
predate the convention (`/n/wallet`, `/n/git`); do not copy
them for new work.
predate the convention (`/n/wallet`, `/n/git`, `/n/wikia`,
`/n/speech`); do not copy them for new work — their migrations
are tracked as INFR-400 through INFR-403.

**Control files, not config files.** A service is configured and
commanded by writing text to its `ctl` file, and reports through
Expand Down
6 changes: 1 addition & 5 deletions docs/DOCUMENTATION-INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
| [evaluations/fractal-app-evaluation.md](evaluations/fractal-app-evaluation.md) | Fractal app production readiness evaluation |
| [architecture-review-veltro-unification.md](architecture-review-veltro-unification.md) | Veltro architecture review |
| [matrix-architecture.md](matrix-architecture.md) | Matrix compositional module runtime — modules, compositions, the library, 9P control namespace, and the Lucifer GUI control surface |
| [9p-data-conventions.md](9p-data-conventions.md) | 9P data conventions Matrix modules read from and write to |
| [9p-data-conventions.md](9p-data-conventions.md) | Data conventions for 9P file servers — text records, hierarchy as schema, ctl files, `/mnt` placement, the no-JSON argument |
| [RECOMMENDED-ADDITIONS.md](RECOMMENDED-ADDITIONS.md) | Recommended feature additions |

## For Developers
Expand Down Expand Up @@ -120,10 +120,6 @@ Detailed JIT documentation is in `docs/arm64-jit/` (27 files covering implementa

See [formal-verification/README.md](../formal-verification/README.md) for TLA+, SPIN, and CBMC verification of namespace isolation (3 tools, 11 properties, 3.17B+ states explored).

## GoDis Compiler

See [tools/godis/README.md](../tools/godis/README.md) for the Go-to-Dis compiler architecture, translation strategy, and 190+ passing tests.

## The Key 64-bit Fix

Pool quanta must be 127 for 64-bit (not 31 as for 32-bit). This single change in `emu/port/alloc.c` was the critical breakthrough that made the entire port work. See [LESSONS-LEARNED.md](LESSONS-LEARNED.md) for the full story.
Expand Down
2 changes: 1 addition & 1 deletion docs/USER-MANUAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ No SDKs. No libraries. No protocol buffers. Just files.

### Namespaces are Private

Every process has its own view of the filesystem. What you see at `/n/web` might not exist for another process. This is the foundation of security: you can't access what isn't in your namespace.
Every process has its own view of the filesystem. What you see at `/mnt/web` might not exist for another process. This is the foundation of security: you can't access what isn't in your namespace.

### Text is Universal

Expand Down
26 changes: 13 additions & 13 deletions man/4/web9p
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ is a 9P file server that exposes HTTP operations as files.
It mounts at
.I mountpoint
(default:
.BR /n/web )
.BR /mnt/web )
and provides a simple filesystem interface for making HTTP requests.
.PP
The filesystem structure is:
.IP
.EX
/n/web/
/mnt/web/
url (w) Write URL to fetch
method (rw) GET or POST (default: GET)
body (rw) POST body content
Expand Down Expand Up @@ -60,30 +60,30 @@ Enable 9P protocol tracing for debugging.
Fetch a web page:
.IP
.EX
web9p /n/web
echo 'https://example.com' > /n/web/url
cat /n/web/result
web9p /mnt/web
echo 'https://example.com' > /mnt/web/url
cat /mnt/web/result
.EE
.PP
POST data to an API:
.IP
.EX
echo 'https://api.example.com/data' > /n/web/url
echo 'POST' > /n/web/method
echo '{"key": "value"}' > /n/web/body
cat /n/web/result
cat /n/web/status
echo 'https://api.example.com/data' > /mnt/web/url
echo 'POST' > /mnt/web/method
echo '{"key": "value"}' > /mnt/web/body
cat /mnt/web/result
cat /mnt/web/status
.EE
.PP
For agent use, the typical pattern is:
.IP
.EX
echo 'url' > /n/web/url && cat /n/web/result
echo 'url' > /mnt/web/url && cat /mnt/web/result
.EE
.SH FILES
.TF /n/web
.TF /mnt/web
.TP
.B /n/web
.B /mnt/web
Default mount point
.SH SOURCE
.B /appl/cmd/web9p.b
Expand Down
Loading