[aurascoper]

Summary

This draft PR proposes the rebased two-way attenuation and 4-panel observer branch (feat/two-way-attenuation-observer) for independent scientific and software review rather than direct merge into master. It also documents the single-line physical-row requirement on data/deferrals.csv in scripts/preflight_merge.sh.

Scientific & Software Review Scope

1. Conservation and normalization of the two-group attenuation cascade (biofilms_potts.jl)

   • Directional ray-marching in update_radiation_field! integrates optical_depth_fast += kappa_eff * ds with I_f_step = I0 * exp(-optical_depth_fast) and I_therm_acc = I_therm_acc * exp(-kappa_th_eff * ds) + Sigma_eff * I_f_step * ds.
   • Effective moderation cross-section is bounded by local fast removal (0 <= Sigma_eff = clamp(Sigma_loc, 0.0, max(0.0, kappa_loc)) <= kappa_eff) with kappa_th_eff = max(0.0, p.kappa * p.kappa_therm) >= 0, ensuring 0 <= I_fast <= I0, I_therm >= 0, radiation == I_fast + I_therm, and 0 <= radiation <= I0 (never multiplying above the unattenuated source even if nominal Sigma_scatter > kappa_species).
   • Verified in BiofilmsPottsRad.run_control_audit() and test_viewer_bundle.py.

2. Energy and state accounting in the poison-burnout surrogate (biofilms_potts.jl)

   • Explicit 5-point stencil in step_fields! with reflection (zero-flux Neumann) boundary conditions satisfies sum(lap) == 0.0 to machine precision on arbitrary grids.
   • Before non-negativity clamping, total grid inventory obeys the exact discrete balance sum(C_new) - sum(C_old) == dt * sum(prod - decay - burn).
   • Verified in BiofilmsPottsRad.run_control_audit() and test_viewer_bundle.py.

3. Distinguishing native OpenMC fields from resampled/extruded display fields (viewer.py, observer.py, biofilms_potts.jl)

   • Every LayerSpec carries native_openmc_field=False, grid_representation="resampled_extruded_display_grid", and authoritative_for_quantitation=False.
   • BiofilmOpenMCObserver declares NATIVE_OPENMC_FIELD = False and GRID_REPRESENTATION = "resampled_extruded_display_grid", and export_observer_payload stamps "native_openmc_field": false.

4. Read-only observer isolation (observer.py, viewer.py)

   • BiofilmOpenMCObserver sets READ_ONLY_OBSERVER = True and AUTHORITATIVE_FOR_QUANTITATION = False, never imports feedback_uq or synthetic_gate, and has no write/feedback/verdict methods.
   • compute_and_validate_layers copies all input numpy arrays so downstream rendering cannot mutate caller raw_state buffers in place.

5. Confirming synthetic neutron/dose outputs cannot be mistaken for measured physical dose (viewer.py, observer.py, biofilms_potts.jl)

   • LayerSpec sets synthetic_surrogate=True and measured_physical_dose=False, with flux units "rel_flux" (never "Gy" or "Sv").
   • Panel 3 scalar bar is explicitly titled "Flux I_tot [rel, synthetic surrogate - NOT Gy]".
   • Replaced legacy radiotrophic_fraction key with melanized_fraction (MELANIZED_FRAC_KEY).

6. Deferral register CSV single-line scope (scripts/preflight_merge.sh)

   • Documented that data/deferrals.csv is validated line-by-line and requires single-line rationales (RFC 4180 single-line subset; embedded newlines inside quoted fields are not supported).

[Copilot]

🟡 Changes recommended

A critical radiation-energy error charges an unchanged source site, allowing identical final lattices to incur different costs, while other unresolved findings affect transport physics, reported quantities, and production-kernel test coverage.

11 open issues

• Copy energy cost incorrectly depends on the source pixel · New
• Down-scattering update introduces resolution-dependent energy loss · New
• Relative flux is mislabeled as mean dose rate · New
• Water cells are incorrectly counted as radiolytic voids · New
• Mesh colors do not match the species legend · New
• Missing precursor damage is silently replaced with melanin · New
• poison_lag is omitted from the shared-shape validation · New
• Two-group attenuation ignores the global kappa multiplier · New
• Void reactivity uses an unmatched baseline and invalid fraction · New
• Tests exercise fixtures instead of production kernels · New
• Output isolation test misses aliases in returned input layers · New

What changed in this PR

This draft adds a synthetic, state-dependent radiation and poison-burnout model alongside the existing biofilm simulation, with a four-panel observer for inspecting its outputs.

Changes:

• Adds a Julia two-group attenuation model, coupled lattice updates, inhibitor dynamics, control audits, and JSON export.
• Adds Python layer contracts, synthetic-field labels, observer rendering, telemetry, and tests.
• Makes the snapshot module’s h5py import optional and documents single-line deferral CSV requirements.

File	Description
scripts/​preflight_merge.sh	Documents the existing single-physical-line CSV restriction; no behavior change.
coupling/​tests/​test_viewer_bundle.py	Adds layer validation, observer rendering, telemetry, and contract checks.
coupling/​biofilm_openmc/​viewer.py	Defines surrogate layer contracts and computes derived display fields.
coupling/​biofilm_openmc/​snapshot.py	Allows module import when h5py is unavailable.
coupling/​biofilm_openmc/​observer.py	Adds the four-panel observer and summary telemetry.
biofilms_potts.jl	Adds the radiation/burnout surrogate, control audits, and observer payload export.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The copy-attempt energy violates detailed balance and the two-group update loses flux under pure scattering, while existing controls do not exercise the production kernels.

12 open issues

• Integrate scattering transfer to conserve flux · New
• Copy energy cost incorrectly depends on the source pixel
• Output isolation test misses aliases in returned input layers
• Tests exercise fixtures instead of production kernels
• Void reactivity uses an unmatched baseline and invalid fraction
• Two-group attenuation ignores the global kappa multiplier
• poison_lag is omitted from the shared-shape validation
• Missing precursor damage is silently replaced with melanin
• Mesh colors do not match the species legend
• Water cells are incorrectly counted as radiolytic voids
• Relative flux is mislabeled as mean dose rate
• Down-scattering update introduces resolution-dependent energy loss

2 previously missed issues

In code that hasn't changed since last review

Sum melanized species only when their types exist

biofilms_potts.jl:2725

N_types is configurable, but this reduction unconditionally indexes species 4 and 5. A valid single-species or three-species state initializes successfully and then throws a BoundsError when computing or exporting its derived layers. Sum only melanized species that exist in sp_counts.

Compare against a matched no-void flux reference

biofilms_potts.jl:2739

This compares a domain-mean two-group flux with a fast-only water value at one assumed path length, so the difference is not attributable to voids. An all-water 8×8 lattice with the default cascade has no voids but reports a coefficient of approximately 139,274 because the unrelated residual is divided by 1e-6. Use a matched no-void calculation and explicitly handle zero void fraction, or label this as a flux residual rather than dI/df_void; the same issue occurs in coupling/biofilm_openmc/viewer.py:732–735.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Unresolved critical errors in the CPM radiation energy change and fast-to-thermal transfer violate the Hamiltonian calculation and flux conservation.

14 open issues

• Integrate scattering transfer to conserve flux
• Copy energy cost incorrectly depends on the source pixel
• Avoid indexing species beyond configured N_types · New
• Exercise production kernels in automated tests · New
• Output isolation test misses aliases in returned input layers
• Tests exercise fixtures instead of production kernels
• Void reactivity uses an unmatched baseline and invalid fraction
• Two-group attenuation ignores the global kappa multiplier
• poison_lag is omitted from the shared-shape validation
• Missing precursor damage is silently replaced with melanin
• Mesh colors do not match the species legend
• Water cells are incorrectly counted as radiolytic voids
• Relative flux is mislabeled as mean dose rate
• Down-scattering update introduces resolution-dependent energy loss

_{Review effort: Balanced}

[aurascoper]

Addressed follow-up items in 69da568:

1. Enforced single-line CSV rationale rule with negative control: scripts/preflight_merge.sh explicitly rejects any physical line in data/deferrals.csv with an odd number of double quotes (unclosed quotes or multi-line quoted fields split across \n) as MALFORMED DEFERRAL ROW, and scripts/test_preflight_merge.sh adds Control (8d) asserting that a quoted rationale containing an embedded newline exits 1 with MALFORMED DEFERRAL ROW.
2. Removed duplicate branch ref: Deleted fix/issues-solo-boost on origin and locally so only feat/two-way-attenuation-observer points to PR feat(rad,observer): two-way state-dependent attenuation, poison burnout, and 4-panel observer contract #81.
3. Manuscript two-way surrogate prose update: Updated preprint/modeling_radioresistance_and_radiotropic_fitness.tex (Section 5 Methods line 600, Section 6 Results line 923, and Appendix planned-feedback line 1716) to state that while the executed OpenMC Monte Carlo snapshot exchange in the 256-seed ensemble is one-way, radiation coupling in the repository code is no longer strictly one-way when the opt-in state-dependent attenuation, two-group cascade, and poison-burnout surrogate (BiofilmsPottsRad, target_calibration=false) is active.

[Copilot]

🟡 Changes recommended

Unresolved correctness defects misreport attenuation, void diagnostics, and precursor data, while conservation tests do not exercise the production Julia kernels.

15 open issues

• Integrate scattering transfer to conserve flux
• Copy energy cost incorrectly depends on the source pixel
• Exercise production kernels in automated tests
• Avoid indexing species beyond configured N_types
• Output isolation test misses aliases in returned input layers
• Tests exercise fixtures instead of production kernels
• Void reactivity uses an unmatched baseline and invalid fraction
• Two-group attenuation ignores the global kappa multiplier
• poison_lag is omitted from the shared-shape validation
• Missing precursor damage is silently replaced with melanin
• Mesh colors do not match the species legend
• Water cells are incorrectly counted as radiolytic voids
• Relative flux is mislabeled as mean dose rate
• Down-scattering update introduces resolution-dependent energy loss
• Describe occupancy-based attenuation and one-way inhibitor field · New

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Critical issues remain: void-free fields can produce spurious void-reactivity coefficients, and snapshots without precursor damage data incorrectly publish melanin as accumulated damage.

8 open issues

• Copy energy cost incorrectly depends on the source pixel
• Fix species allocation for the three-species ablation · New
• Exercise production kernels in automated tests
• Tests exercise fixtures instead of production kernels
• Void reactivity uses an unmatched baseline and invalid fraction
• Missing precursor damage is silently replaced with melanin
• Mesh colors do not match the species legend
• Relative flux is mislabeled as mean dose rate

8 resolved since last review

• Integrate scattering transfer to conserve flux
• Avoid indexing species beyond configured N_types
• Output isolation test misses aliases in returned input layers
• Two-group attenuation ignores the global kappa multiplier
• poison_lag is omitted from the shared-shape validation
• Water cells are incorrectly counted as radiolytic voids
• Down-scattering update introduces resolution-dependent energy loss
• Describe occupancy-based attenuation and one-way inhibitor field

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The copy-energy calculation depends on the unchanged source site's flux, producing a nonzero copy/undo cycle cost that violates Hamiltonian consistency.

10 open issues

• Copy energy cost incorrectly depends on the source pixel
• Void coefficient uses unmatched fast-flux baseline · New
• Fix species allocation for the three-species ablation
• Exercise production kernels in automated tests
• Tests exercise fixtures instead of production kernels
• Void reactivity uses an unmatched baseline and invalid fraction
• Missing precursor damage is silently replaced with melanin
• Mesh colors do not match the species legend
• Relative flux is mislabeled as mean dose rate
• Burnout contours include geometry outside the clipped plane · New

_{Review effort: Balanced}