diff --git a/AGENTS.md b/AGENTS.md index e64db58b1..0dc8d292b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d1f37315..f37326d60 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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). @@ -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 diff --git a/appl/xenith/IDEAS.md b/appl/xenith/IDEAS.md index 58500bfd9..a63b07bee 100644 --- a/appl/xenith/IDEAS.md +++ b/appl/xenith/IDEAS.md @@ -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 diff --git a/docs/9p-data-conventions.md b/docs/9p-data-conventions.md index a5c43bd12..fe89798f5 100644 --- a/docs/9p-data-conventions.md +++ b/docs/9p-data-conventions.md @@ -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/`, 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/`, 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/`, 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//` 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 @@ -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 @@ -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 @@ -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 @@ -131,7 +161,7 @@ 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 @@ -139,7 +169,7 @@ 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 @@ -147,7 +177,7 @@ 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 ``` @@ -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 @@ -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 @@ -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 diff --git a/docs/DESIGN-PRINCIPLES.md b/docs/DESIGN-PRINCIPLES.md index 2a1449775..008fbbb02 100644 --- a/docs/DESIGN-PRINCIPLES.md +++ b/docs/DESIGN-PRINCIPLES.md @@ -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. @@ -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 diff --git a/docs/DOCUMENTATION-INDEX.md b/docs/DOCUMENTATION-INDEX.md index 2b509536e..ebb7f28f7 100644 --- a/docs/DOCUMENTATION-INDEX.md +++ b/docs/DOCUMENTATION-INDEX.md @@ -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 @@ -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. diff --git a/docs/USER-MANUAL.md b/docs/USER-MANUAL.md index c7af15ada..2e8c9f21e 100644 --- a/docs/USER-MANUAL.md +++ b/docs/USER-MANUAL.md @@ -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 diff --git a/man/4/web9p b/man/4/web9p index 0f0827cad..636662c4e 100644 --- a/man/4/web9p +++ b/man/4/web9p @@ -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 @@ -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