Concepts and decisions
One move, repeated: replace a guess with a calculation.
Additive-only file structure
Rhizoid-managed metadata (manifest, sync state) is added as new files alongside upstream's own, never edited in place inside upstream's existing files. This keeps a pull from upstream conflict-free for the tracked branch - not a guarantee that any patch to upstream code stays conflict-free, only that Rhizoid's own bookkeeping never collides with it.
Adopt an existing fork vs create a new one
Two different, deliberately separate operations: rhizoid add forks a new copy of upstream; rhizoid import points at a fork that already exists (with or without the rhizoid wrapper already on it) and adopts it into the manifest without creating anything. Kept as two verbs rather than one flag with a default, the way terraform keeps import separate from apply - the two operations have different blast radii and a wrong default in either direction is a real mistake (an unwanted duplicate fork, or silently overwriting someone's existing, satisfactory fork).
argenv declares flags and env vars - not subcommands or positionals
Read argenv's own source and README before designing against it: it is explicitly "a declared, typed contract for a program's invocation surface - argv and envp", and every Input it declares binds to a --flag/env-var pair, never a bare positional value. Confirmed by reading argenv-cli's own main.rs (the author's own reference CLI): subcommand dispatch is a plain match on args.first(), not anything argenv provides. Rhizoid's CLI follows the same shape: a thin hand-written dispatcher picks the verb and reads each command's one primary positional (a repo spec, a URL, a module name) directly; argenv declares only the named flags for each verb.
Auth: shell out to gh, for now
Rhizoid calls the GitHub CLI (gh) for anything needing authentication - forking, merge-upstream, reading repo state - rather than managing its own token or OAuth flow. Whoever already has gh authenticated can use Rhizoid immediately; the tool has no credentials of its own to store, rotate, or leak. Revisit if a use case needs something gh cannot do (a non-GitHub git host, for one).
Clean patch back upstream
Because Rhizoid's own metadata never touches upstream's files, a diff of the patch branch against the pristine tracking branch is a clean patch, submittable as a normal PR to the original repo, whether or not its owner has ever heard of Rhizoid.
No central lockfile - state is distributed into each fork
Cargo, npm, Poetry and Nix all pair a human-edited manifest with a separate, machine-written lockfile recording exact resolved state. Rhizoid does not need a top-level lockfile: each managed fork is already a real git repository with its own history, and its own .rhizoid/module.toml already carries that module's exact recorded state (see [module-metadata-file](concepts.md#module-metadata-file)). A central lockfile would just be a second, independently-driftable copy of information git already holds per-repo.
Status detects drift, not just reports the manifest
rhizoid status inspects the real state of every managed fork (does it exist, what commit is the tracking branch actually at, is there uncommitted or unmanifested structure) and diffs that against the manifest's record, the way terraform plan diffs real infrastructure against Terraform state. The manifest is a record of intent, not a source of truth Rhizoid trusts blindly - reality always wins the comparison.
Fork destination is a manifest setting, not hardcoded
Where a new fork lands (which org or account) is configured per manifest, with a default and a per-module override - the same shape as west's remotes list (a named set of url-bases) plus each project's optional remote: override. Nothing about Rhizoid assumes forks live in one specific org.
The manifest is TOML, with the footgun that argues against it named up front
TOML: native comments (unlike JSON), no implicit type coercion or indentation sensitivity (unlike YAML - see [the YAML document from hell](sources.md#yaml-document-from-hell)), and its array-of-tables syntax is a direct fit for "a list of modules, each a flat record". Cross-ecosystem adoption for exactly this kind of file (a hand-editable project/tool manifest, not a deeply-nested orchestration config) is real and independent of any one language: Cargo.toml, pyproject.toml, Hugo, Netlify. The honest counter-case: Cloudflare's Wrangler shipped TOML-only for years, then added JSONC and now recommends it for new projects, naming TOML's array-of-tables syntax as a real footgun in practice - a misplaced or missing [[table]] header silently puts a value in the wrong entry (see [the future of Wrangler configuration](sources.md#wrangler-toml-to-jsonc)). That risk is highest when a file is mostly hand-typed from scratch, which is not the common case here: the manifest is meant to be edited through add/import/remove, not freehand, and each module's own detailed state lives in its own .rhizoid/module.toml rather than piling many [[module]] entries into one large hand-edited file - closer to Cargo.toml's [dependencies] table (mostly tool-written) than to a large hand-maintained Wrangler config.
Each fork carries its own .rhizoid/module.toml
The additive metadata that makes a fork "attached" lives in a new .rhizoid/module.toml file at the fork's own root: origin URL, tracked ref, pinned commit, whether it was added or imported, when. Mirrors .tad/.gitrepo's pattern from the tad system - a plain, readable file is the source of truth for state, not something buried in commit messages or a separate database.
The v1 command surface: init, add, import, update, status, refresh, remove
init sets up a manifest. add forks a new module into the configured org and starts tracking it. import adopts an existing fork without creating one. update pulls upstream into a module's tracking branch (GitHub's merge-upstream). status reports drift between the manifest and real git/GitHub state. refresh reconciles the manifest to match observed reality without changing anything (mirrors terraform apply -refresh-only) - this is how a by-hand change gets folded back in rather than flagged as drift forever. remove drops a module from the manifest. send-upstream (clean patch back to the true upstream) is real but deferred to v0.2, after the core loop is proven.
Two crates: rhizoid-core and rhizoid-cli
Mirrors argenv's own workspace shape (crates/argenv + crates/argenv-cli). rhizoid-core holds the Manifest and Module types, their JSON Schema (via schemars, the same crate argenv itself already uses for its own contract feature), and the GitPort/GitHubPort traits the real fork/sync logic will implement later. rhizoid-cli holds argv dispatch and the per-command argenv Models. Splitting now, before there is much code, avoids a disruptive later refactor once the planned TUI needs to depend on the same core logic without the CLI.
Rhizoid-cutting (rhizcut)
A single dependency managed by Rhizoid: a real GitHub fork of an upstream repo, owned and pinned rather than referenced remotely. Named after a horticultural cutting - a piece taken from a parent plant and rooted separately, genetically identical at the start but independent from then on.
Tracking branch vs patch branch
The branch that mirrors upstream is never hand-edited - only fast-forwarded via merge-upstream. All customization lives on a separate branch that merges from the tracking branch. The tracking branch never conflicts; the patch branch might, exactly once, when upstream touches a line you also patched - that is inherent to patching, not a tooling failure.
Replace a guess with a calculation
Which version is this, what does it need, does it need rebuilding, do these conflict, what may it touch, who is affected by this flaw, are these two things the same: each is guessed today and becomes a calculation once things have stable identities.
Why: It is the whole idea; everything else is engineering.
The three mistakes, and the one beneath
Things are identified by name; versions describe whole components; boundaries are treated as walls - and beneath all three, isolation is the default and connection is work. All inherited from tape drives that read one file at a time, never designed.
Why: Software interacts: that is what it is for. Connection should be the default, isolation the declared exception.
Identity by what a thing is
A definition is identified by a fingerprint computed from its own contents plus the fingerprints of everything it depends on (a Merkle tree; mutually dependent groups are fingerprinted together). Names become labels pointing at fingerprints.
Why: Rename, move, reorganise - nothing breaks; and 'is this, and everything beneath it, exactly the same?' is answered by one number.
Structure, not text
The fingerprint is computed from the structure of the code - formatting, spacing and the names of internal variables fall away (alpha-equivalence). Two people making the same change in different styles produce the same fingerprint.
Why: Identical work is recognised as one thing and stored once. The honest limit: different methods reaching the same answer are never recognised as identical.
The graph is the source of truth
What is stored, hashed, compared and edited is resolved structure. Text appears once on the way in and once on the way out, at one marked boundary; nowhere between is text anything but a derived rendering.
Why: Lose this and it becomes git with hashes without anyone noticing the day it happened.
There are no files
With every reference a fingerprint, imports have no job, and then files have none: there is a graph of definitions and links, looked at through views - slices you choose and switch between, typing ordinary code, navigating relationships instead of folders. Your layout is remembered as yours; authors may suggest a reading order.
Why: A relationship can hide in files; in a view computed from real relationships it is in front of you by default.
The closure
Start from what you want, follow every reference, stop when nothing new appears: exactly what is needed, nothing more.
Why: You take the behaviour, not the box it shipped in.
Grafting
Taking a piece of someone else's software into yours: its closure arrives, attaches, and remembers where it came from so improvements can go home. Wrap what exists, replace it gradually underneath.
Why: One function arrives as eleven definitions you can read, not a library with three hundred and forty dependencies.
Changing is not editing
A changed thing is a different thing with a different fingerprint; the original stands and its users are unaffected. The chain above re-points with small records - 'same as before, except this reference' - bounded by your project. A succession link notes lineage.
Why: It deletes version numbers, dependencies as commonly understood, and merge conflicts: 'I fixed it in my fork' becomes a stable end state that costs nothing.
Frozen, with a path to fixes
Nothing updates unless you say so - which also means nothing is silently fixed. So: who is affected is a lookup; a fix arrives classified (drop-in, needs conversion, needs a rebuild); and per item you pin, follow, or defer to someone you trust. When two you trust disagree, you are shown both.
Why: Resolve disagreement automatically and everyone converges on whichever authority is fastest - a central gatekeeper rebuilt.
Layers that can only add
Architectures, bindings, shims, features: each an additive piece with a condition on it, inert unless the condition holds - never fetched, never built, structurally unable to break anyone it does not apply to.
Why: A maintainer can accept a contribution without checking whether it breaks everyone else.
No configuration files
Arguments, environment variables, configuration files and build flags exist because the finished program is a sealed box. A value is another item in the graph; configuring is pointing a reference elsewhere. Authors mark intended settings as exposed; some values genuinely arrive only at runtime.
Why: There is nothing left to smuggle in.
Secrets as handles
Secrets are never in the graph (nothing can be deleted from it, and fingerprints of short values can be reversed). The graph holds a handle resolved outside it when the program runs.
Why: Rotation is free, handles can be weakened, revocation is instant - capability security.
Folklore becomes evidence
A measurement attaches to the exact value it concerns, with its conditions - this hardware, this workload, this result - and because the configuration is exact, anyone who doubts it can reproduce it.
Why: Advice about settings has always been untestable; what is worth trusting is the evidence and its conditions, never the number alone.
Stop searching the internet for your own computer
Every exposed value carries its names, its author's default, its explanation in place, its lineage, what it affects and what others measured; search narrows to what you are actually running, and alternative names anyone adds become search terms.
Why: Documentation rots because it is a copy of the truth; here there is one thing.
The program is a receipt
The graph is the valuable thing; the program is a consequence recomputed from it, a cache entry nothing refers to. Understanding code is done once for everyone; preparing it for a machine is the cheaper half; only what actually changed rebuilds; results are stored by fingerprint too, so values sit beside the code.
Why: One mechanism gives compilation caching, configuration and live values.
Everything visible, almost nothing present
The machine appears to hold the entire tree of all software; a thing arrives the instant it is needed - done at the filesystem so every existing tool works unchanged.
Why: Three organisations built this independently for their own codebases: the shape is forced, not arbitrary.
One kitchen, many dishes
A long-running process keeps the shared groundwork warm; each program starts as a copy-on-write copy of it, in its own memory space.
Why: The boundaries removed are filing conventions; the physical one that contains a crash stays.
Absent, not forbidden
The list of pieces that built a program is its entire visible world: what it does not need is not denied to it - it is not there.
Why: A sandbox nobody wrote and nobody can get wrong: it falls out of a calculation done for another reason.
Changing things while they run
Calls go through an index of where each thing lives; replacing a thing is updating its entry. Whether a change can go live is computed beforehand: inside of a function - swap; shape of stored data - convert first; a boundary - restart.
Why: Live updating stops being try-it-and-hope.
Rigor as a dial
The same definitions expressed loosely - copying freely, vague errors, like a scripting language - or tightly - explicit ownership, no copying, precise types - tightened where a real wall is met; and tightening done once lives on the definition for everyone.
Why: Working software on the first evening; learning driven by meeting a real limit.
Conjuring a shoot
You do not install software: you point at the rhizome, draw a boundary, and a working shoot materialises. The shoot and its names are yours and die with the conjuring; only the changed substance goes home.
Why: There is no dev environment and no separate kind of person: a user who hits a bug is already looking at what caused it.
It behaves like a living system
Fingerprints are the genes and names the appearance; the Weismann barrier - the shape you drew and the name you gave stay yours, only substance is inherited; grafting is lateral gene transfer; renaming is a silent mutation; settings are gene regulation; disuse is how things die.
Why: A model that keeps making correct predictions in a field it was not built for is probably carved along the real joints.
Assembly, not invention
Every layer runs in production somewhere: structural identity (Unison), whole-tree-visible stores (Google, Microsoft, Meta), reversible slicing (josh), optional parts that stay unbuilt (the Linux kernel), fine-grained change analysis and edition morphing (Rust), the zygote model (Android), live patching (Linux).
Why: Nobody has put them in the same room; and the patient authoring it needs has become cheap.
The first user ahead on day one
The risk is not the engineering but adoption: the first person to use it must come out ahead at once, alone, with no community behind them.
Why: Systems that asked people to invest first for a payoff later did not succeed.
Hypha
The first milestone: the content-addressed core. It reads real Rust, fingerprints every definition by structure and dependencies, keeps them in one shared graph per machine, and turns a chosen piece back into running code (graft).
Why: Three small steps - identity, graft, sync by difference - make a tool worth using on its own, and are the thesis made testable.
Ingest talks to a small persistent daemon that keeps the analysis warm; reads against the store are a stateless command.
Loading and resolving a workspace is expensive and worth keeping warm; the daemon is the first instance of the later genome process.
Rejected: A fresh process for every call.
2026-09-09
Structure is extracted with rust-analyzer's own semantic layer (ra_ap_hir), pinned, behind a stable SymbolGraph boundary; everything downstream speaks language-agnostic graph types.
Real name resolution as a library on stable Rust; the boundary insulates from its 0.0.x instability and is where another language's extractor plugs in.
Rejected: The compiler's internals, MIR or a nightly-only interface; writing a parser or resolver.
2026-09-09
Graft - a closure turned back into compilable, running code - is in the first milestone.
If the structure cannot go back into something executable there is no point in it; proving the round trip first tests the representation before anything is built on it.
Rejected: Ending the first milestone at ingest, hash, store, sync.
2026-09-09
The graph is the source of truth, without qualification; text is read once on the way in and emitted once on the way out.
Describing it as 'a store of source text indexed by structure' quietly re-centres files - the old world with a hash bolted on.
Rejected: Text as the content with structure as its index.
2026-09-09
H(node) = blake3(postcard(hash form) ++ sorted references); local names replaced by positions; cycles condensed and hashed as one unit.
Deterministic, structural, fast; alpha-equivalence built in from the start because it changes what the hash is.
Rejected: Hashing text; adding alpha-equivalence later.
2026-09-09
The kernel is not in the prototype; its only near-term role is the filesystem view, stages later.
'Rust in the kernel' is an argument about timing, not a build target; kernel work is the slowest feedback there is.
Rejected: Starting at the kernel.
2026-09-09
Sync is proven between two local stores before any network transport.
Deciding what to transfer is the part worth testing; the transport is mechanical after.
Rejected: Starting with the network.
2026-09-09
Macros are expanded on the way in and not preserved as such.
They are a convenience of text-based development; once the structure itself is edited they have no job.
Rejected: Treating macros as something the graph must round-trip.
2026-09-09
The project is Rhizome - a root system with no root, any point connecting to any point; its foundational engine is Hypha, the single filament; the tools are rz and hy. The substrate is the rhizome, definitions are nodes, a conjured shape is a shoot.
Biology is load-bearing in the model, so the vocabulary comes from the same well.
Rejected: Alkahest; Aleph (taken); Mycorrhiza (the most exact, the hardest to spell).
2026-09-09
No new language: the host language's type system expresses boundaries and transformations.
Inventing a language to avoid using one was Nix's mistake.
Rejected: A DSL.
2026-09-09
One shared store per machine (~/.local/share/hypha/store); a project holds only a hypha.lock - a small pointer file of closure roots.
A store per project would be isolated and non-deduplicating: the very thing the manifesto opens by attacking.
Rejected: A hidden .hypha per project, like .git.
2026-09-09
The compiler is a black-box oracle at the single text boundary - today the only socket it has; Cranelift is the named long-term destination for code generation.
It keeps the first milestone free of compiler engineering while naming where the text boundary finally disappears.
Rejected: Treating the round trip through text as the destination.
2026-09-09
Hypha is to be developed from its own graph, proven by a fixpoint: built from the graph, it ingests and re-emits itself to the identical hash. Files and git demote to a projection.
The field's answer to the trust hazard of self-hosting systems, and the hardest stress test for free.
Rejected: Keeping its own source in files for ever.
2026-09-09
Each node keeps its verbatim source span beside its hash form; graft emits the original bytes, never a reconstruction.
Nothing is inferred on the way out; the structural hash is identity, the text a rendering of it.
Rejected: Regenerating text from stripped structure.
2026-09-09