3.6 The instruction plane: what fully describes a tenant
A useful way to think about an RS2 tenant is to separate its instructions (how it behaves) from its data (what it holds). RS2 draws this line sharply, and the line is itself a feature.
The parts of the instruction plane
A tenant's behavior is completely described by:
- The tenant config — the JSON document of mounts and settings.
.rs2-code/— deployed custom-service bundles (JS/Wasm), content-addressed by version..rs2-pipelines/— stored pipeline specs..rs2-queries/— stored query specs..rs2-templates/— stored compiled template specs.
The last three live at well-known prefixes inside the tenant's file store. Everything else under the file/data stores is data and assets — the records, the uploaded files, the application content.
More precisely — and so this stays true as new spec stores are added — the
instruction plane is a rule, not a fixed list: the tenant config, plus
every mount that advertises a specSubtree on the discovery surface
(/.well-known/rs2/services), plus the pinned code versions its config
references. Pipelines, queries, and templates are today's spec stores; a new one
joins the instruction plane the moment it declares its authoring subtree, with
no special-casing by name. This is exactly what rs2 pull/push rely on (see
below).
Why the separation matters
It's mechanically extractable. Because the instruction plane follows this
discoverable rule, the full "source code" of a tenant can be pulled out, diffed, and
restored as a unit — independent of the (possibly large) data. This is what
rs2 pull/rs2 push use to version-control how a tenant behaves without
dragging its data into git (Appendix E / the CLI reference): pull mirrors the
instruction plane into a local rs2/ directory, push sends edits back through
the validated, ETag-guarded APIs — git never runs in-process.
It explains where things go. Pipelines, queries, and templates are authored
like files under reserved dot-subtrees (/<mount>/.pipelines/…,
/<mount>/.queries/…, /<mount>/.templates/…) — and
now you know why: those subtrees are the instruction plane surfacing through the
normal store contract. Deployed code lands in .rs2-code/<name>/<version> for the
same reason.
It keeps runtime state out. Operational/runtime state (sessions, logs, idempotency records) is deliberately not part of the instruction plane. The instruction plane is meant to be reproducible config-as-data; mixing in ephemeral state would break that.
What this means for you
- When you author a pipeline, query, or template, you're writing into the instruction plane through the store contract — which is why those edits feel like file edits.
- When you want to capture "how this tenant is built," it's the tenant config plus its discovered spec subtrees and pinned code — not a database dump.
- A deployed code bundle is immutable per version and addressed by content, so an instruction plane is a precise, pinned description, not a moving target.
That completes the conceptual core. You now have the model — messages, mounts,
the store pattern, patterns/facets, capabilities, and the instruction plane — to
read the rest of the manual as applications of a few ideas. Part 4 starts with
the two stores you'll use most: file and data.
← Previous: 3.5 Capabilities and the sandbox · Manual home · Next: Part 4 — 4.1 The file service →