# Logbook — 2026-04-13 — WP-E v0.3 decisions

**Context.** WP revised from v0.2 → v0.3 incorporating Guardian v0.2 and
external v0.2 reviews. This entry records the decisions taken on Q0–Q8,
the preflight protocol specification, and the Hamiltonian-code line that
fixes the φ_α sign convention.

-----

## 1. Decisions on open questions Q0–Q8

| Q   | Decision                                                             | Status                                 | Section in v0.3 |
|-----|----------------------------------------------------------------------|----------------------------------------|-----------------|
| Q0  | WP-E — Forward Map and Observability (new node)                      | Resolved                               | §1, §8          |
| Q1  | Observable = complex C + σ_z                                         | Resolved                               | §2, §8          |
| Q2  | 2D slices S1/S2/S3 (Option B); 3D cube deferred                      | Resolved                               | §4, §8          |
| Q3  | Reference models R1, R2, R12; residuals Δη, Δt, cross                | Resolved; LD closed-form TBD           | §3.1, §4, §8    |
| Q4  | δ₀ ±6 MHz; |α| ∈ {0,1,3,5}; **φ_α ≥ 48, 64 preferred**               | Partial — resolution details post-preflight | §8          |
| Q5  | Extend `stroboscopic_sweep.py` (default); new file only if invasive  | Conditional — decide after preflight   | §8              |
| Q6  | φ_α anchored to engine Hamiltonian (see §2 of this entry)            | Resolved                               | §2.2, §8        |
| Q7  | Pure-state unitary; reopens if §4a D2 trips                          | Resolved with gate                     | §2, §4a, §8     |
| Q8  | Fix N = 22; |C| normalised to reference state (|α|=0, δ₀=0, φ_α=0)   | Resolved                               | §2.1, §8        |

Q0 was resolved in favour of the external reviewer's recommendation
(WP-E, a new observable-forward-map node) rather than folding into WP-B
or WP-A.1. Rationale: the forward map is the object every downstream
injectivity/backaction claim depends on; giving it its own node makes
that dependency auditable.

The π/2 inconsistency (N · θ_pulse = 1.53 rad vs. π/2 = 1.571 rad) was
resolved by acknowledgement rather than parameter adjustment (A2, E3).
Adjusting θ_pulse to 1.571/22 = 0.0714 rad would require retuning Ω_eff
or δt, which misrepresents the nominal device parameters. Defining |C|
relative to the reference state (§2.1) removes the ambiguity without
touching the parameters.

## 2. Hamiltonian-code line fixing the φ_α sign convention

Reference: [../../scripts/stroboscopic_sweep.py](../../scripts/stroboscopic_sweep.py).

**Primary anchor — coherent-state preparation (line 103):**

```python
alpha = alpha_abs * np.exp(1j * theta)   # with theta = np.radians(alpha_phase_deg)
```

This is the unambiguous definition of φ_α in the engine: the complex
phase of the coherent-state amplitude α passed to the Fock-basis expansion.

**Supporting anchor — displacement generator (line 138):**

```python
gen = alpha * adag - np.conj(alpha) * a   # D(α) = exp(α a† − α* a)
```

Standard Wigner-convention displacement operator. Combined with the
position quadrature definition `X = a + adag` (line 88), this fixes:

- φ_α = 0   →   coherent state on +X̂ axis in phase space (⟨X̂⟩ > 0, ⟨P̂⟩ = 0);
- φ_α = π/2 →   coherent state on +P̂ axis.

**Coupling Hamiltonian — line 198–200:**

```python
H[:nmax, nmax:] = (omega_r / 2) * C        # ↓↑ block (σ₋), C = exp(iη X)
H[nmax:, :nmax] = (omega_r / 2) * Cdag     # ↑↓ block (σ₊)
```

with C = exp(iη(a + a†)) constructed at line 96 via `expm(1j * eta * X)`.
This confirms that the stroboscopic analysis pulse couples through the
exponential-in-X operator and that all sign conventions for ∂C/∂φ_α
follow from the chain:

```
alpha (line 103)  →  D(α) (line 138)  →  X̂ = a + a† (line 88)  →  H_int = (Ω/2)(C σ₋ + C† σ₊) (line 199–200)
```

**Consequence for the WP.** Every residual plot's φ_α sign is interpreted
in this convention. Any future engine (new `phase_contrast_map.py` or a
rewrite) must reproduce the φ_α → (⟨X̂⟩, ⟨P̂⟩) mapping bit-for-bit at
preflight anchor.

## 3. Preflight protocol (§4a of v0.3)

**Anchor point.** (δ₀ = 0, |α| = 0, φ_α = 0).

**Engines under test.**
1. HDF5 adaptive-learner (legacy — produced 0.61/0.71/0.84/0.75 contrast series).
2. JSON-uniform engine (legacy — produced ≈ 0.56 contrast).
3. Candidate engine (extended `stroboscopic_sweep.py` or new
   `phase_contrast_map.py`).

**Observables recorded per engine.**
- Per-pulse Bloch vector (⟨σ_x⟩, ⟨σ_y⟩, ⟨σ_z⟩) at pulse indices 1 … 22.
- Accumulated phase arg C(0, 0, 0).
- Final contrast |C(0, 0, 0)| (raw, not yet normalised).

**Gate outcomes.**
- Agree within integrator tolerance → proceed to §4 deliverables;
  legacy engines used for spot-check cross-validation.
- Disagree with cause identified among (i) φ_α sampling, (ii) hidden
  ensemble averaging, (iii) Ω vs Ω_eff calibration, (iv) integrator
  tolerance → publish logbook entry, patch/document/quarantine, re-run.
- Disagree with no identified cause → main sweep paused; mismatch becomes
  a WP-E sub-deliverable.

**D2 clause.** If the legacy engines' noise models are not documented to
be identical to the candidate engine's pure-unitary configuration, Q7 is
reopened before the main sweep — not after.

## 4. Outstanding actions

- [ ] Code-reading pass on [../../scripts/stroboscopic_sweep.py](../../scripts/stroboscopic_sweep.py)
      to confirm:
      (a) whether ⟨σ_x⟩, ⟨σ_y⟩ are exposed or require backend patch (Q1 + Q5);
      (b) whether a closed-form LD linear prediction exists for R1 (Q3);
      (c) runtime estimate for 64 × 121 × 5 = 38,720 runs (Q4).
- [ ] Separate task: update cross-references in
      [../../ARCHITECTURE.md](../../ARCHITECTURE.md) and
      [../../ideal-limit-principles.md](../../ideal-limit-principles.md)
      with the WP-E node. Not modified in v0.3 per the non-goals clause
      of the revision task.
- [ ] Preflight run (§4a). First logbook entry after this one should
      report preflight results.

## 5. Files touched in this revision

- [../README.md](../README.md): v0.2 → v0.3 full rewrite incorporating
  Blocks A–H of the Guardian task specification.
- [this file]: new logbook entry.

No code changes to [../../scripts/stroboscopic_sweep.py](../../scripts/stroboscopic_sweep.py)
or to [../../ideal-limit-principles.md](../../ideal-limit-principles.md)
were made, per the non-goals clause.