# FOCUS_AND_ANCHORING.md

GrowNet Focus & Anchoring V1 adds a first-class, optional focus layer on top of the existing Python runtime.

It does not replace the baseline runtime. It adds explicit runtime concepts for:

- active focus point
- active anchor/reference
- remembered anchor map
- serial focus selection
- pluggable focus policies

## Core Terms

### Focus Point

The focus point is the currently selected candidate input location or value being routed right now.

- In scalar paths this is the current scalar input value.
- In focused 2D paths this is one selected `(row, col)` candidate at a time.

### Anchor

An anchor is the reference point used to interpret later inputs.

- Scalar slotting already uses a FIRST anchor per neuron.
- Spatial slotting already uses FIRST or ORIGIN anchors per neuron.
- Focus V1 makes the active anchor explicit at the region focus layer as well.

### Anchor Map

The anchor map is a small remembered set of meaningful focus points.

- anchors are created when selected candidates matter enough to enter focus
- revisits update existing anchors
- old anchors expire deterministically if unused long enough

V1 keeps this intentionally small and deterministic. It is not a giant spatial memory system.

## Serial Focus

GrowNet focus is serial, not simultaneous.

- a frame may produce multiple candidates
- one active focus point is selected at a time
- remaining points may still be remembered in the anchor map
- focused 2D routing may process more than one candidate serially in one tick when config allows it

This is not transformer attention. It is a serial selection-and-routing mechanism layered on top of GrowNet's existing routing and slotting.

## Covert vs Overt Focus

### Covert / Field Focus

Focus V1 implements covert focus only.

- select candidates from an existing field/frame
- choose one active focus point
- route the selected signal serially

### Overt / Mechanical Focus

Future work only.

- no camera/head/body movement simulation in this PR
- no robotics-style sensor repositioning in this PR

## Focus Policies

Supported V1 policies:

- `energy_first`
- `random_candidate`
- `sequential_scan`
- `novelty_first`
- `familiarity_first`

These policies are deterministic for the same seed/config.

## Anchor Modes vs Focus Policies

Do not conflate these.

- anchor mode governs how a neuron's slot anchor is established
- focus policy governs how the region chooses the next active candidate

Current truthful V1 anchor-mode surface:

- scalar slotting: `FIRST`
- spatial slotting: `FIRST`, `ORIGIN`

Focus policies sit above slot selection. They choose what gets routed next. Slot selection still decides where the routed signal lands inside the neuron's memory structure.

## 2D Focused Routing

Baseline `Region.tick_2d(...)` remains the honest per-pixel path.

Focused routing is optional:

- use `Region.tick_2d_focused(...)`
- or enable `focus.enabled` in experiment config for rank-2 runs

Focused 2D flow:

1. generate sparse/salient candidates from the frame
2. score them with the configured focus policy
3. apply lightweight inhibition of return
4. select one candidate at a time serially
5. update the active anchor and anchor map
6. route the selected candidate through the existing 2D runtime path

If focus is disabled, the baseline `tick_2d()` path is preserved.

## Trace Surface

Focus V1 adds these trace events:

- `focus.candidates`
- `focus.select`
- `focus.shift`
- `focus.return_inhibited`
- `anchor.create`
- `anchor.update`
- `anchor.revisit`

These events are best-effort like the rest of the trace system.

## Config Surface

Experiment configs can enable focus with:

```json
{
  "focus": {
    "enabled": true,
    "policy": "energy_first",
    "serial": true,
    "candidate_limit": 8,
    "allow_anchor_map": true,
    "inhibition_of_return_ticks": 3
  }
}
```

This config still defines only the initial scaffold plus focus behavior. GrowNet remains free to grow afterward.
