Env NodeSet Template (Gym-like Interface)

The interface contract every interactive (MDP) env nodeset should implement so simulators expose one consistent surface. It keeps Gymnasium's four verbs — reset / step / close / observe — but adopts a pull-style perception model that fits VLN/EQA: step is a pure transition that returns no observation, and observe is the on-demand channel a method uses to fetch exactly the information it wants. Action and observation spaces are node-naming axes, not runtime config: each env exposes a step_<actionspace> family and an observe_<obsspace> family, all sharing fixed return contracts.

All five MDP env nodesets implement this contract (since 2026-06-10). Which env supports which spaces is registry information, not contract — see the capability matrix in the env catalog. The 2026-06 migration record (old→new node maps, pre-refactor audit) lives in this page's git history.

1. Interface taxonomy — where this template applies

env/ currently holds three interface types, separated by two axes: does the nodeset have an episode lifecycle, and does it have an action loop (do the agent's actions change what it observes next)? This template (§3–§5) specifies only the first type; the other two are listed so a new env nodeset gets classified deliberately instead of inheriting whatever shape its upstream code had.

Three boundary rules fall out of the table:

• A replay benchmark keeps the lifecycle half of the env contract and drops the interaction half. env_openeqa_em has reset, episode iteration, metric emission, and an env panel with episode selection + play/pause/stop — everything except step. It is exempt from this template, not an outlier of it (its nodes deliberately kept their pre-gym names — renaming would have broken three verified graphs for a purely cosmetic change).
• A stateless service is not an env interface type at all — locate_2d / segment is the same request→response shape as the model/ servers (vlm_prismatic, model_sam). DetAny3D sat in env/ by historical placement until 2026-07-04, when it moved to model/model_detany3d per the layout standard's membership test (its three verbs are generic detection primitives — the label space comes from the caller, not from ToolEQA). No lifecycle-less nodeset lives in env/ anymore; don't add new ones.
• Variation inside the MDP type is parameterization, not a new type. Action-space suffixes (step_discrete vs step_continuous), observation-space suffixes, and env_libero's privileged GT observation space (observe_objects) all ride the same four-verb contract; none of them justifies a new row above.

The two-axis matrix has one empty cell — action loop without episode lifecycle. That is the continuing / real-time environment (a physical robot, a live world): no reset (the world cannot be rewound), no episode boundary, and time does not pause between step and observe — which breaks gym's lockstep assumption. If the platform reaches real-robot deployment, that type arrives as a contract change, not as one more nodeset under this template. Other conceivable shapes — trajectory replay of recorded (obs, action) demonstrations for offline training, turn-based multi-agent — become relevant only if the platform's scope grows to cover them; no verb surface is reserved in advance.

2. Why, and why not vanilla gym

Env nodesets are pure tools (decoupled-nodeset principle): observe / step / episode-control surfaces, no method reasoning. Before this contract (pre-2026-06), each env had grown its own surface and they didn't line up — step returns differed per env, reward was exposed nowhere, done had no terminated/truncated split, and observe/step each went by 3–5 different names. The contract exists so a method written against one env finds the same verbs, the same port shapes, on every other env.

Vanilla gym fixes naming but assumes a model we don't have: gym observations are env-pushed and fixed-schema (declared by observation_space, returned every step), so they ride on step. Ours are agent-pulled and parametric — a method asks for a panorama (n_views=12), a single egocentric view, or the navigable-viewpoint graph, on demand, and panoramas are expensive enough that you must not render one every step. That is gym's render() role, not its observation. So we split transition from perception.

3. The model: four verbs, pull perception

A typical agent loop becomes: observe_* → reason → step_* → observe_* → …, with the loop's continue-condition reading terminated / truncated off the last step. The method pulls exactly the modalities it needs each iteration, and pays for expensive observations (panorama) only when it asks.

Episode selection (split / episode_index / play) stays env panel-owned — the gym gym.make(id) analog, not a node. A thin evaluate metric-sink node is kept outside the four verbs (decision E, §7); it fires once in the after-loop band (triggered by the iterOut's final_stop) and reads the env's terminal metrics.

4. Spaces as naming axes

Action and observation spaces are not graph nodes and not runtime config — they are a fixed vocabulary that names the step_* / observe_* node families and types their ports. Each env declares which spaces it supports and exposes the matching nodes. Cross-env unification = this vocabulary is shared and each suffix carries the same port contract everywhere, so a method that wants waypoint nav looks for *__step_waypoint and gets the same shape on every env that has it.

4.1 Action spaces → step_<x>

4.2 Observation spaces → observe_<y>

Reuse an existing suffix before inventing one — a new space name is a vocabulary change that every future env inherits. Which env implements which suffix is tracked in the capability matrix, not here.

5. Return contracts

5.1 reset

Begins an episode and emits episode-level metadata only (the gym info at episode start). These ports are env-specific because the metadata is — VLN carries instruction, EQA carries question — but the rule is fixed: no observation, no rgb/depth. The first frame comes from a following observe_* call.

Reset is an idempotent ensure-live: if the previous episode is done (a canvas re-run — reset fires once in the pre-loop band, before any observe), it re-arms an episode in place; a live episode — the batch-eval path, where the runner has just placed a fresh one — is read without disturbance. Episode placement (which episode) stays env panel-owned; reset never chooses, only revives (decision I, §7).

• VLN (habitat / mp3d / simpler): instruction, episode_id, scene_id
• EQA (hmeqa / openeqa): question, choices/answer_gt, episode_id, scene

5.2 step_<x>

Input varies by action space (§4.1). Output is fixed across the whole family — every step_* on every env emits at least these four control ports:

The wire-type registry (app/standard/wire_types.py) has no FLOAT or DICT type — ANY is the canonical carrier for scalars and plain dicts. So reward and info ride ANY; terminated/truncated use BOOL.

Env-specific extra outputs may sit alongside the four (mirrored inside info): the manipulation envs (env_simpler, env_libero) add success + step_index convenience taps, and env_libero__step_ee_pose adds converged / final_pose / step_count / error. The four-port contract is a floor, not a ceiling — agents wiring extras accept env coupling, exactly as with reset's env-specific metadata.

5.3 observe_<y>

Input is a bare trigger (perception is a read of current state, idempotent). Output ports are the obs-space payload from §4.2. No control signals — observe never advances the env, and performs no lifecycle action: observing a finished episode returns the terminal frame unchanged, never a fresh episode. Rollover ownership lives in reset (decision I, §7) — the ADR-012-era auto-reset inside observe_* was removed 2026-06-11 because a post-loop re-fire of an observe could silently roll the env into a new episode under evaluate.

5.4 close

Suite-level teardown owned by the env panel/manager, not a graph node. Per-episode close is forbidden for SIMPLER (SAPIEN 2.2.2 GC ordering segfault); mirror the upstream no-close pattern.

6. Checklist: what a new env nodeset provides

The contract above fixes the node surface; this is the fill-in-the-blanks list for shipping a new MDP env nodeset under it.

• Classify first (§1). If there is no action loop, you are building a replay benchmark or a service — this template does not apply.
• Three-layer file shape: a singleton manager owning the simulator handle (single-thread executor if the sim has GL/thread affinity) · tool nodes implementing the verbs · a NodeSet binding (get_tools / initialize / shutdown).
• Nodes: reset (§5.1) · one step_<x> per supported action space (§4.1, return contract §5.2) · one observe_<y> per obs space (§4.2, §5.3) · a thin evaluate sink. Reuse existing space suffixes before inventing one.
• Env panel: placement cascade fields (e.g. split → episode_index) + the play / pause / stop / reset action quartet; field changes and the reset action emit the episode_reset signal carrying the cascade snapshot, while play re-seats the selected episode via set_episode and returns run_start (a panel response carries one side effect — no shipped env emits a signal from play). See the env-panel design doc.
• NodeSet ClassVars: server_python = conda_env_python("<env>", "<VAR>_PYTHON") for a dedicated conda env · parallelism = "replicated" for stateful sims · default_per_step_budget_sec matched to step latency · optional replay_parser.
• Eval integration: get_eval_metadata() (splits, episode counts, metrics, step budget) so batch eval can drive the env.
• Ship with: an install script scripts/install/install_<env>.sh (creates the conda env; initializes any third_party/ submodules it needs) and a row in the env catalog tables.

7. Decisions