onf-c2/docs/GLOSSARY.md

# Glossary

Every term used in this repo, defined once. Grouped by concept, not alphabetised — terms that are
easy to confuse sit next to each other on purpose.

---

## Naming

**ONF** — the Python package name (`src/onf`), expanding to "Oriented Neural Field". Historical.
The current method is not a neural field. Treat `onf` as an opaque package name.

**cleanliness field** — the one component that is still a field: a 136,216-parameter MLP mapping a
joint configuration to a scalar distance-to-manifold. Stored as `onf_head.npz`.
→ [technical/02 §2.1](technical/02-retrieval-head.md)

---

## The graph

**node** — one run of up to `COARSEN = 5` consecutive raw frames from a single demonstration, cut
short at any gripper state change so that every node has exactly one gripper state. `long` suite:
28,476 nodes over 500 demos. → [technical/01 §1.2](technical/01-data-and-graph.md)

**raw frame** — one timestep of the original LIBERO HDF5 trajectory. `long` suite: ~131,000 raw
frames total, ~4.6 raw frames per node (below `COARSEN` because gripper flips force early cuts).

**strand** (`owner`, `[V] i4`) — which *demonstration* a node came from. 500 strands in `long`.

**lane** (`task_id`, `[V] i2`) — which *task* a node came from. 10 lanes in `long`. Strands nest
inside lanes: 50 strands per lane.

**phase** (`[V] f4`) — position within an episode in **raw-frame** space: `arange(T)/(T−1)` evaluated
at the node's first frame. `0.0` = first frame, `1.0` = last. Comparable across demos of different
lengths. Used for binning, masking and cross-demo comparison.

**t_frac** (`[V] f4`) — position within an episode in **node** space:
`t_idx / (n_nodes_in_demo − 1)`. Fed to the network through `psi(t_frac)`.

> `phase` and `t_frac` are both in [0,1] and both mean "how far along". They are **not**
> interchangeable. They differ because coarsening is not uniform. Using one where the other is meant
> selects the wrong nodes with no error raised.
> → [technical/01 §1.3, "Easy to get wrong"](technical/01-data-and-graph.md)

**phase bin** — one of `NBINS_ALIGN = 20` equal buckets over `phase ∈ [0,1]`. The single bucketing
every phase histogram in the subsystem agrees on (`onf/graph/core/binning.py`).

**phase_conv** — a string stamped into `g_nodes.npz` recording which phase convention produced it
(`"arange(T)/(T-1) full"`). Re-checked on load; a mismatch raises.

**relation** — one of the `R = 12` edge types. The GNN embeds relation *types*, not nodes, so a
relation that happens to be empty in some graph is legal and must still run.

**dilation** — the hop length of a `next`/`prev` relation, in node steps: `DILATIONS = (1,2,4,8,16)`.
Load-bearing: with `next1` only, 3 message-passing layers reach 3 nodes ≈ 15 raw frames, while a
pre-grasp approach spans ~80 raw frames.

**sibling** — kNN edge to a *different demo, same task, same gripper state*. Out-degree
`K_SIBLING = 8`. Relation index 10.

**align** — kNN edge to a *different task, same phase bin, same gripper state*. Out-degree
`K_ALIGN = 4`. Relation index 11.

**stage** (`[V] i2`) — cumulative count of gripper releases along a demo. Diagnostic only. Nothing in
edge construction, training or retrieval reads it, and there is deliberately no `stage` relation.
→ [technical/01 §1.5](technical/01-data-and-graph.md)

**log_idf** (`[V] f4`) — an additive prior on the output logit, computed from sibling degree
(GFM-RAG eq. 15–16). Stored in `g_edges.npz`.

**graph_hash** — a hash of the `(g_nodes, g_edges)` pair, stamped into `g_head.npz` and
`g_track.npz`. Node ids are positional and meaningless across builds, so a head loaded against a
foreign graph returns confident, correctly-shaped logits on the wrong strands. The hash check is the
only thing that catches this. → [technical/05](technical/05-artifacts.md)

---

## Two heads, similar filenames, different models

| | `g_head.npz` | `onf_head.npz` |
|---|---|---|
| what | the **GNN retrieval head** | the **cleanliness field** |
| input | a window of 8 joint states `[8,7]` | one joint config `[7]` |
| output | a distribution over all 28,476 nodes | one scalar |
| trained by | `onf.graph.train` | `onf.field.train` |
| params | independent of `\|V\|` (inductive) | 136,216 |
| read by | `GraphRetriever`, `GraphTracker` | `ONFField.f_value` → query pooling weights |

These are two different models in two different files. `g_head` scores nodes. `onf_head` scores how
much to trust each frame of the query.

---

## Query and retrieval

**query** (`Q`) — a window of `HIST_H = 8` consecutive joint states, plus their finite-differenced
velocities and gripper flags. `HIST_H` equals one policy action chunk.

**cleanliness weight** (`w`, `[8]`) — `sigmoid(−f(q_i))` where `f` is the cleanliness field.
Pooled through `softmax(log w)`, not `w / sum(w)`, so that `w_i == 0` gives a hard zero rather
than `0/0`.

**seed set** — the `SEED_TOPK = 256` nodes given non-zero initial state `h0`. Everything outside the
seed set starts at exactly zero, preserving the NBFNet semantics of "representation of `v`
conditioned on a seeded source set".

**reachability** — whether message passing ever delivered a message to a node from a seeded source.
Tracked explicitly, not inferred from `h == 0` (`layer_norm` can zero a reached node's state).
Unreached nodes get logit `−inf`.

**abstain** — a scalar logit produced by a separate head, compared against
`logits[reached].max()`. Trained on the same comparison performed at deploy time, with the node
term detached so it never drags the ranking logits.

**entry stratum** — the mask applied when `GR_ENTRY_BAND > 0`: `task lane ∩ phase ≤ band (0.05) ∩
reachable`, with the current demo's own strand excluded (leave-one-demo-out). ~229 of 28,476 nodes
on the `long` graph.

**move cost** — `‖q_node − q_now‖`, passed as the third input to the readout MLP instead of being
applied as a hand-written argmin. The network learns how much to penalise motion, including
accepting a longer move when it is more confident.

---

## Training

**pretext task** — given a window ending at raw frame `T`, predict the node at `T + ADVANCE`
(0 raw frames, i.e. the window's own end) on the same demo. Requires traversal, not lookup: the
window is a trajectory, and the transition kernel — not the head — owns how far forward to look.

**TRAVERSAL / ENTRY / ENTRY_STATIC / DRIFT** — the four query classes drawn by `make_queries`.
`ENTRY_STATIC` (share 0.15) produces `repeat(q0, 8)` — velocity identically zero — because that is
the exact input shape a settled arm produces at deploy time and no other class generates it.
`DRIFT` (share 0.15) is the only class with a clean-to-perturbed breakpoint inside the window; every
other class is uniformly clean or uniformly perturbed, so none of them poses the question of which
rows of a history are still trustworthy.
→ [technical/02 §2.4](technical/02-retrieval-head.md)

**provenance vs consequence** — `is_clean` records which branch generated a query. 
`abstain_is_correct` records whether abstaining is the right behaviour for it. An ENTRY sample with a
tiny perturbation is still on-support, so the loss label uses consequence, not provenance.

**INTER_DEMO_SPACING** — the median leave-one-demo-out nearest-neighbour distance between nodes:
"how far apart independent demos usually sit". Measured, not chosen — ~0.054 rad on the `long` graph.

**LODO** — leave-one-demo-out. Used for the perturbation floor, `INTER_DEMO_SPACING`, and the basin
geometry quantiles.

**hard negative** — a mined distractor, `N_NEG = 16` per query across three buckets: same `t_idx`
different strand; near in `q` but far in `phase` (self-intersection, ~4.1% of frames); and the
query's own nearest neighbour when it is not the answer.

---

## Sentinel (t > 0)

**belief** (`b_t`, `[V]`) — a distribution over graph nodes maintained across checks.
`b_t ∝ [(1 − ε)·P·b_{t−1} + ε·L_t] · L_t`.

**check** — one sentinel evaluation, every `SN_CHUNK = 8` env steps (one policy action chunk), over a
window whose rows are `SN_GRAPH_STRIDE = 1` env step apart. A check advances ~1.65 nodes at ~4.85 raw
frames per node.

**transition kernel** (`P`) — `[(1−β)I + β·M_sib] · Σ_a π_a S_a`. Sibling-mix laterally, then push
forward along the advance mixture. Built from `TRACK_KERNEL_RELATIONS = next1..next16 + sibling`;
`align` and all `prev` relations are excluded on purpose.

**advance set** — `TRACK_ADVANCE_SET = (0,1,2,4,6,8,12,16)` raw frames. Mixed over, not
point-estimated, because a check advances a fractional number of nodes and rollouts run slower than
demos. `a = 0` (the stall self-loop) is mandatory.

**leak** (`ε`) — the restart weight. Restarts toward the *current observation* `L_t`, not toward
uniform. A uniform restart puts mass on impossible phases and discards the aliasing suppression the
filter exists to buy.

**basin** — the certified region around a node, fitted per `(task, phase-bin)` from held-out clean
demo replays: radius `r` = p95 and KDE bandwidth `h` = p50 of LODO nearest-neighbour distances.

**r_eff** — `max(r − h, 0)`. The sentinel target is
`q* = q_now + max(0, 1 − r_eff/‖q_b − q_now‖)·(q_b − q_now)`: exactly `q_now` when already inside,
otherwise the point on the segment at distance `r_eff` from the anchor. Undoes drift down to the
boundary and stops.

---

## The blend

**tracking chunk** (`a_track`, `[K, 6]`) — the reference segment restated in the policy's own action
units. Row 0 is measured against the LIVE pose (feedback), row `k` against `ee_ref[k-1]`
(feedforward). → [technical/03 §3.2](technical/03-action-chunk-blend.md)

**action scale** — metres per action unit for dims 0:3 and radians per action unit for dims 3:6,
fitted off the demos into `action_scale.json`. Two scalars, not one: they differ by 8.8×. Rotation is
*composed* in the world frame, never subtracted.

**blend** — `a_exec[:, 0:6] = (1−α)·a_policy + α·a_track`, applied once per chunk at the refill line.
Dim 6, the gripper, passes through untouched — the command is binary.

**alpha** (`α`) — the blend weight. Either a fixed scalar (`SN_BLEND_ALPHA`) or, under
`SN_BLEND_LEARNED`, a `[K, 6]` array from `AlphaNet`: one weight per chunk row and per pose block.

**`SN_BLEND_SCALE`** — a multiplier on the learned alpha. The chunk-MSE objective fits the right
per-check *shape* at too confident a *level*, so the head is rescaled onto the average authority a
fixed weight was measured to work at. Derived per head, not swept.
→ [technical/03 §3.6](technical/03-action-chunk-blend.md)

**bound** / **`ACTION_LIMIT`** — the row-0 saturation, `bound·tanh(row0/bound)`, at 1.0 action unit.
Row 0 is an unbounded pose error and the simulator clips actions to `[-1, 1]`; this is the deleted
servo's gain limit restated in action space. A constant, not a learned parameter — the one run that
learned it drove it to 24.5.

**corrupted retrieval** — a training row given a deliberately wrong retrieval (`WRONG_TASK`, `OFFSET`,
`WRONG_PHASE`) with the regression target left correct. The only rows on which alpha's gradient can
point down. → [technical/03 §3.7](technical/03-action-chunk-blend.md)

---

## Evaluation

**base** — the frozen policy, untouched. The only definition of a mode is `evals/common/modes.sh`;
both benchmark drivers parse that file so the recipes cannot drift apart. The other modes are
`blend` (alpha 0, a plumbing check), a family of fixed-alpha probes (`blend_a05`, `blend_a015`,
`blend_bounded`, `blend_a015_bounded`, …) and the learned-weight arms (`blend_scaled015`,
`blend_full`). `blend_full` is the current recipe.

**suite** — one of `object`, `spatial`, `goal`, `long`. Maps to a LIBERO dataset directory
(`long` → `libero_10`, **not** `libero_long`).

**axis** — one perturbation axis in LIBERO-Plus: `Robot_Initial_States`, `Light_Conditions`,
`Background_Textures`, `Sensor_Noise`, `Language_Instructions`, `Objects_Layout`,
`Camera_Viewpoints`.

**cell** — one (suite × axis × mode × policy) result.

**rung** — one step of the eval ladder in `configs/sr_ladder.yaml`. `R1` is the 24-episode smoke test.

**churn** — the fraction of episodes that flip outcome between two identical runs. GR00T-N1.7 is
flow-matching and unseeded: ~11.2% churn. StableVLA: 0 churn measured over 393 episodes.

**dead artifact** — written to disk but read by nothing: `q_manifold.npz`, `q_manifold_full.npz`.
Verified by grepping `np.load` across `src/`, `tests/`, `scripts/`, `evals/`.

---

## Constants quick reference

Full table with CHOSEN / DERIVED provenance: [`technical/06-config-reference.md`](technical/06-config-reference.md).

| constant | value | where |
|---|---|---|
| `COARSEN` | 5 raw frames per node | graph build |
| `DILATIONS` | (1,2,4,8,16) node steps | graph build |
| `K_SIBLING` / `K_ALIGN` | 8 / 4 | graph build |
| `NBINS_ALIGN` | 20 phase bins | everywhere |
| `KERNEL_BW` | 0.15 rad | Gaussian edge-weight default; INIT of the learned seed `sigma` |
| `HIST_H` / `SEG_K` | 8 / 8 | one policy action chunk |
| `SEED_TOPK` | 256 nodes | seeding |
| `LAYERS` | 3, weights shared | GNN |
| `GR_ENTRY_BAND` | 0.05 phase | entry stratum mask |
| `SN_CHUNK` | 8 env steps | sentinel check spacing |
| `SN_GRAPH_STRIDE` | 1 env step | sentinel window row spacing |