resonance-engine/OBSERVER_SWEEP_BUILD_SPEC.md

# OBSERVER-DRIVEN SYSTEMATIC INVESTIGATION — BUILD SPEC
**Written 2026-07-14. Build target for the coding agent. Back-checked by oversight after build.**

## PURPOSE
Stop testing single frozen operating points. Give the observer LLM its hands on the lattice's knobs
(omega, khra_amp, gixx_amp) and let it run a full automated sweep of variables AND combinations,
chase anomalies, and adapt — with an interactive mode where the human can steer it to points of
interest. This maps what the substrate ACTUALLY DOES across its parameter space before we claim to
know what it is.

## WHAT ALREADY EXISTS — EXTEND, DO NOT REBUILD
- `build/khra_gixx_1024_v5_observer` — daemon. Live command surface on ZMQ 5557:
  `set_omega`[0.5,1.99], `set_khra_amp`[0,0.2], `set_gixx_amp`[0,0.1], `snapshot_now`,
  `stress_snapshot_now`, `health_check`, `inject_density`, `save_state`, `load_state`.
  Coarse field stream on 5561 (32x32x6, ~100Hz). Telemetry on 5556. **The knobs already turn live.**
- `navigator/lattice_observer.py` — existing observer. READ IT FIRST. Extend it.
- `navigator/zmq_raw_bridge.py` — existing command bridge to 5557. Use it; don't reinvent.
- `navigator/telemetry_server.py`, `sentry_monitor.py` — existing telemetry plumbing.
- `analysis/*.py` — existing analysis (capture_and_predict, baseline_orbit, etc.). Reuse the readers.
**First task of the build: read these files and report what's reusable BEFORE writing anything new.**

## NON-NEGOTIABLE CONSTRAINTS (violating any = the whole sweep is contaminated)

1. **≥10-FORCING-PERIOD AVERAGING FOR ALL SPATIAL READOUTS.** Buried, hard-won rule: short averages
   make the khra/gixx carriers ADD instead of CANCEL, manufacturing FALSE spatial nulls. khra carrier
   ~251 cyc, gixx ~15.7 cyc. Any spatial measurement MUST average >=10 khra periods (>=~2510 cycles)
   or it is an artifact. The whole coarse-stream analysis tonight was in the false-null regime. Fix this.

2. **THE GOVERNING VARIABLE IS THE COUPLING RATIO alpha, NOT omega alone.**
   alpha = (A_khra * omega_gixx * lambda_gixx) / (A_gixx * omega_khra * lambda_khra).
   omega=1.97 is just one value alpha takes at current amplitudes. Sweeping one knob = sweeping one
   input to a ratio = a 1D line through a space governed by the COMBINATION. Sweep combinations.
   Compute and log alpha at every grid point.

3. **NODAL MULTI-ATTRACTOR AWARENESS.** The founding Nodal Aether hypothesis: the lattice is a network
   of nodes, each a small attractor; a lattice of this size = a SUITE of attractors. Global averaging
   (9 scalars, or even 32x32) collapses the suite into one smooth mode — which is why everything looked
   like a single global attractor. The sweep must probe for MULTIPLE basins, not assume one. Do not
   declare "one attractor" from averaged data.

4. **RIGOR (unchanged, it's working — caught 6+ false positives).** Every anomaly/claim: pre-committed
   threshold in code BEFORE looking; surrogate/permutation null; bootstrap distribution (never single
   sample); threshold NOT within one noise-width of the value. A clean null is a real result.

5. **SAFETY.** Clamp all knobs to daemon-valid ranges. Never reset_equilibrium casually. Restore baseline
   (omega 1.97, khra 0.03, gixx 0.008) and leave the field as found at end of each run. Launch daemon
   DETACHED (setsid, poll log) — executor times out at 30s. Only ONE daemon holds ports 5556-5561.
   NEVER touch canonical khra_gixx_1024_v5.cu.

## STAGE 1 — AUTOMATED SWEEP ENGINE (`analysis/sweep_engine.py`)
A controller that drives the live daemon through a parameter grid and characterizes each point.

- **Grid:** 3 axes — omega, khra_amp, gixx_amp. COARSE pass first (e.g. omega {1.4,1.6,1.8,1.9,1.97,1.99},
  khra {0.01,0.03,0.06,0.1}, gixx {0.004,0.008,0.02,0.05}) = ~96 points. Refine hot regions after.
  Grid is config-driven so it can be expanded without code changes.
- **Per grid point:**
  1. Set knobs via 5557 bridge. Wait a SETTLE period (>=10 khra periods, ~2510+ cyc) for the field to
     reach its attractor at the new parameters. Confirm settle by telemetry stabilizing.
  2. Capture a MEASUREMENT window from 5561 (>=10 khra periods) with proper averaging.
  3. Compute and log, per point: alpha; limit-cycle character (does coherence orbit? period? amplitude?
     or does it go fixed / chaotic / blow up?); short-horizon predictability (persistence vs linear, the
     +21% metric from tonight); mass-leak rate (density drift slope); dynamical richness / effective
     dimension of the coarse field; and a MULTI-BASIN probe (does the field settle to the same place from
     different phases, or are there distinct settling points?).
  4. Save raw capture + computed metrics to a durable per-point file (resumable — sweep must survive a
     crash and continue, given it takes days).
- **Output:** a growing `sweep_results.jsonl` (one line per point) + raw captures. A map of alpha-space:
  where the system is boring/stable, where chaotic, where predictability peaks, where leak is worst,
  and — the prize — where perturbations would hold longest (the candidate "memory" regime).
- **Resumable + detached + logged.** Days-long. Poll a progress file. Never inline in the executor.

## STAGE 2 — OBSERVER ANOMALY-CHASING (extend `navigator/lattice_observer.py`)
Give the observer LLM agency over the sweep: not just execute the grid, but ADAPT to what it sees.

- The observer receives each point's metrics as they compute. Its job: watch for ANOMALIES — points
  where a metric jumps, a new orbit character appears, predictability spikes, the field does something
  the smooth-global-mode picture doesn't predict.
- When it flags an anomaly, it can request the sweep engine to REFINE around that point (finer grid,
  longer capture, multi-basin probe) — chasing the anomaly instead of blindly finishing the grid.
- **Prompt (write to `navigator/sweep_observer_prompt.json` or similar):** frame it as CHASE ANOMALIES,
  not confirm expectations. Explicitly: "You are mapping an alien system across its parameter space. You
  do NOT know what it is. Look for where its behaviour CHANGES CHARACTER — transitions, new modes,
  regimes where perturbations persist. When you see an anomaly, chase it: request a refined sweep there.
  Do NOT force it into a brain analogy or any expected shape. Report what changes and where. Time is a
  variable — how long things persist matters as much as their magnitude. A boring flat map is a real
  result; do not manufacture excitement." Include the false-null averaging rule and the alpha ratio in
  the prompt so the observer reasons with them.
- **Kill the drift:** the observer must NOT reach for Golden Weave, other LLMs, or narrative. Its only
  moves are: request a sweep point, request a refinement, report a metric-grounded observation. Every
  claim needs the Stage-1 rigor. No poetry.

## STAGE 3 — INTERACTIVE HUMAN-IN-LOOP MODE (`analysis/sweep_interactive.py` or a mode flag)
A mode where the human can steer the observer to points of interest during a trial.

- Live view: current knob settings, current metrics, the alpha-space map so far (which points done, what
  they showed). Reuse `field_viz.html`-style rendering for the live coarse field if feasible.
- Human can: jump the daemon to any (omega, khra, gixx); ask the observer to dwell and characterize a
  point; ask it to sweep a custom line/region; mark a point as interesting for later refinement.
- The observer explains what it's seeing at the current point and suggests where to look next — the human
  can accept, redirect, or override. Two-way.
- Implementation can be a simple CLI or a lightweight local web UI — agent's call, justify the choice.

## BUILD ORDER (do in sequence, report after each)
1. Read existing navigator/ + analysis/ files; report what's reusable. (No new code yet.)
2. Stage 1 sweep engine — get ONE grid point working end to end (set knobs, settle, capture with proper
   averaging, compute metrics, save). Verify against oversight BEFORE running the full grid.
3. Run coarse grid (days). Resumable, detached.
4. Stage 2 observer anomaly-chasing on top of the running sweep.
5. Stage 3 interactive mode.

## DELIVERABLE
A running, resumable, days-long automated sweep of omega x khra x gixx that produces a map of alpha-space
with per-point dynamical characterization (all with >=10-forcing-period averaging), an observer that
chases anomalies within it, and an interactive mode for human steering. The goal is ONE thing: find out
what the substrate actually does across its parameter space — especially WHERE (if anywhere) perturbations
persist and WHERE the behaviour changes character — before we design any memory experiment.