Current OpenTendril architecture

A Pollinator is an external requester that reaches in and asks for governed work: a Botanist at a terminal, or an external client over a governed interface. It is not a Sprout.

A Pollen is the identity (principal) a Pollinator presents and a grant names. Authentication and authorisation are separate steps.

On credential-bearing governed routes, the Stem authenticates the credential and derives the Pollen from it; a caller-declared identity is not trusted on those routes. Other current paths can use declared Pollen, for example in-process MCP.

Grants live in the Stem’s own control-plane directory, not inside a Substrate checkout that could self-escalate. Transport-specific credential headers and mint endpoints belong in operational guides (see Docs), not as the architecture’s centrepiece.

The Stem is the deterministic Go orchestrator, lifecycle kernel, and governed capability registry. Narrow responsibilities:

• deterministic routing and orchestration;
• session and lifecycle coordination;
• the governed Core registry;
• grant and authority enforcement on the current control path;
• coordination of execution and inference ports.

The Stem can contain deterministic business and governance logic in Core. The invariant is not “the Stem contains no business logic.” The invariant is:

governed command authority belongs in Stem Core;
transport adapters do not independently implement it

The Stem is the deterministic Go orchestration and governance kernel. LLM reasoning remains in the external Mycorrhizal Network; the Stem does not reason.

Roots are OpenTendril’s own provider and client connectivity layer: model discovery, provider clients, and routing that reach into the external ecosystem.

The Mycorrhizal Network is the external probabilistic LLM: the mind that reasons and holds no durable OpenTendril state of its own.

The LLM remains external to the deterministic Stem architecture. Provider names are secondary; the architecture is provider-independent at the conceptual level.

A Branch is a capability group (security zone) initialised by the Stem, not a Git branch. (Git branches are source-control refs; see Git & human acceptance.)

That taxonomy definition alone does not establish physical isolation between Branches; no stronger enforcement claim is made here without implementation evidence.

Keep these three separate:

• Sprout Ephemeral execution worker (body) that does one unit of work.
• Terrarium Isolation boundary (filesystem and network) around a Sprout.
• Stoma The single controlled aperture in a Terrarium wall through which commands enter and results leave. A Terrarium has exactly one.

Sprout ≠ Terrarium. The body is not the wall. Concrete Stoma transport is provider-specific. Firecracker materializes Stoma communication through the guest init process over vsock; that transport detail does not make the Stoma taxonomy optional.

Current Terrarium providers

The Stem implements a provider contract with these current providers:

• Docker: underlying Docker provider and fallback runtime. The low-level terrarium.NewProvider factory also resolves an empty provider name to Docker.
• gVisor: Docker with the runsc runtime. Normal Conductor selection prefers gVisor when the host’s Docker daemon has runsc registered and no explicit provider override is supplied (for example via TENDRIL_TERRARIUM_PROVIDER or a Substrate provider setting); otherwise it falls back to Docker.
• Firecracker: KVM micro-VM provider when explicitly selected and available.
• Host: explicit isolation bypass requiring TENDRIL_ALLOW_HOST_EXECUTION=true; runs with full host-user permissions.

These are mechanics, not security rankings. Details and threat-model notes: Consequence containment.

A Substrate is the repository being worked on: the soil under cultivation.

Execution commonly uses isolated working contexts so work does not freely rewrite an operator’s live checkout:

• ordinary local Sprout paths often use a shadow worktree; when merge-back is enabled (the default for many ordinary runs), a successful commit can be fast-forwarded into the host checkout (local workspace Git reconciliation, not Botanist acceptance);
• seed and some review-preserving paths disable that merge-back so work stays on a dedicated line for review;
• delegated Git operations (commit, push, PR, and related classes) are separately granted and do not all fire on every path.

Not every execution path has the same Git handoff. The Objective is the capability under test, not a claim that every current path already satisfies its final Git-handoff condition. See Git & human acceptance.

Observation sits beside execution, not as a routine approval gate:

• EventBus: in-process typed pub-sub for run lifecycle, tools, health, and related events;
• /ws: WebSocket observation surface over that bus (not a command capability);
• run and history endpoints: persisted history and REST observation surfaces when enabled;
• sprout.watch: view authority for delegated observation without handing out grow rights;
• Greenhouse: the Command Center UI a Botanist watches through.

Greenhouse is not the Stem and not reasoning. It is an observer surface. Full treatment: Observability without routine approval.

Fruit is Git-reviewable output a cycle yields: a branch, pull request, or artifact. The Botanist decides acceptance.

Fruit does not automatically merge. A single commit is not synonymous with Fruit. Current implementation contains several Git paths; Git & human acceptance describes their handoff and acceptance implications.

Architecture exists to make governed autonomous work inspectable: freedom inside a boundary, observation without routine approval, and Git as the acceptance handoff. Those problem statements live on Why, Harnesses, Containment, Observability, and Git. What OpenTendril is testing is on Experiment.