From 65ec70886f17b3e4397accbe2d925a00e5aa453a Mon Sep 17 00:00:00 2001 From: pdfinn Date: Sat, 22 Aug 2026 04:02:55 +0700 Subject: [PATCH 1/3] docs: drop Go from the contributor-facing surface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Go-to-Dis compiler is experimental and nothing is built from it; presenting Go as a repo language invites agents to write Go for InferNode features. AGENTS.md now states application code is Limbo, never other languages; the GoDis contribution section, directory-table row, and index section are removed. The pedagogical uses stay — 'Limbo is close to Go' is orientation, not an invitation. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_017Eo29oZp7mPig1XekwRPsq --- AGENTS.md | 2 +- CONTRIBUTING.md | 12 ------------ docs/DOCUMENTATION-INDEX.md | 4 ---- 3 files changed, 1 insertion(+), 17 deletions(-) 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/docs/DOCUMENTATION-INDEX.md b/docs/DOCUMENTATION-INDEX.md index 2b509536e..f995c2ad6 100644 --- a/docs/DOCUMENTATION-INDEX.md +++ b/docs/DOCUMENTATION-INDEX.md @@ -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. From 54fc6b2881d49e37a45be8ccdf0e1a0095bc4805 Mon Sep 17 00:00:00 2001 From: pdfinn Date: Sat, 22 Aug 2026 04:07:15 +0700 Subject: [PATCH 2/3] docs: 9p-data-conventions examples follow the placement convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc predates NAMESPACE-LAYOUT.md and demonstrated every example service at /n/* — app-authored schemas that belong under /mnt by the schema-authorship rule. All 23 example paths converted, and a new 'Where to mount it' section states the principle up front (authored schema -> /mnt even when data is remote; foreign tree imported intact -> /n; the convention is security work; legacy /n/wallet and /n/git are not to be copied) with the full argument deferred to NAMESPACE-LAYOUT.md. Same inherited idiom fixed in DESIGN-PRINCIPLES' worldview example (/n/sensors -> /mnt/sensors) and USER-MANUAL's philosophy tenet (/n/web -> /mnt/web, where webfs actually lives). Index description of the conventions doc generalized. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_017Eo29oZp7mPig1XekwRPsq --- docs/9p-data-conventions.md | 76 ++++++++++++++++++++++++++----------- docs/DESIGN-PRINCIPLES.md | 2 +- docs/DOCUMENTATION-INDEX.md | 2 +- docs/USER-MANUAL.md | 2 +- 4 files changed, 56 insertions(+), 26 deletions(-) diff --git a/docs/9p-data-conventions.md b/docs/9p-data-conventions.md index a5c43bd12..d21e8cf33 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 +(`/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..9232aa2a4 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. diff --git a/docs/DOCUMENTATION-INDEX.md b/docs/DOCUMENTATION-INDEX.md index f995c2ad6..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 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 From 7b4f51e5c44b6377306760efa0fd15e92bff939a Mon Sep 17 00:00:00 2001 From: pdfinn Date: Sat, 22 Aug 2026 04:17:03 +0700 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20full-corpus=20placement=20sweep=20?= =?UTF-8?q?=E2=80=94=20/n=20vs=20/mnt,=20every=20occurrence=20classified?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two agents examined every /n/ occurrence across docs/ (112 files), man/ (all sections), docs subdirs, appl/**/*.md, lib/veltro text, and root docs, against NAMESPACE-LAYOUT.md's schema-authorship rule. Fixed: man/4/web9p (13x /n/web -> /mnt/web — documents an app-authored schema; its stated source appl/cmd/web9p.b does not even exist) and appl/xenith/IDEAS.md's web9p proposal (9x). Everything else classified: live legacy paths kept accurate (/n/wallet, /n/git, /n/wikia, /n/speech — now annotated in DESIGN-PRINCIPLES and 9p-data-conventions with their migration tickets INFR-400..403), genuine imports kept (/n/local, peer roots, device trees), historical records left untouched. Also carries the re-cut of two commits orphaned by the #518 merge: the Go removal from the contributor surface and the 9p-data-conventions /mnt example conversion. Refs: INFR-400, INFR-401, INFR-402, INFR-403 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_017Eo29oZp7mPig1XekwRPsq --- appl/xenith/IDEAS.md | 18 +++++++++--------- docs/9p-data-conventions.md | 2 +- docs/DESIGN-PRINCIPLES.md | 5 +++-- man/4/web9p | 26 +++++++++++++------------- 4 files changed, 26 insertions(+), 25 deletions(-) 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 d21e8cf33..fe89798f5 100644 --- a/docs/9p-data-conventions.md +++ b/docs/9p-data-conventions.md @@ -33,7 +33,7 @@ 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 +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 diff --git a/docs/DESIGN-PRINCIPLES.md b/docs/DESIGN-PRINCIPLES.md index 9232aa2a4..008fbbb02 100644 --- a/docs/DESIGN-PRINCIPLES.md +++ b/docs/DESIGN-PRINCIPLES.md @@ -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/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