v0.2.2 — prob_floor denormal-overflow fix + A=1 cleanup ledger

v0.2.2 -- prob_floor denormal-overflow fix + A=1 cleanup ledger

dcl_core v0.2.2 is a two-part patch to the prob_floor feature added
in v0.2.1:

1. a bug fix -- prob_floor no longer NaN-poisons the state when a
   continuous wavepacket's exponential tail underflows to deep
   denormals; and
2. an additive, read-only ledger -- CausalSession.floor_ledger()
   reports exactly how much probability the floor manufactures (the
   A=1 cleanup budget).

It exists to unblock dcl-delta-p-min's Phase 2 4-cell grid, whose
core column (exp_18_dp_min_grid, exp_09_dp_min_floor,
exp_12_dp_min_sweep) runs prob_floor on narrow tidal-ionization
packets over large lattices -- exactly the regime that surfaced the
denormal bug.

This is not v1.0.0. The formal API freeze remains gated on
dcl-delta-p-min finishing and co-releases with Paper III.

Semver: PATCH. The fix changes only previously-NaN results
(finite results reproduce to ~1 ulp); the ledger is purely additive and
read-only; prob_floor=None (default) is still bit-for-bit the
v0.2.0/v0.2.1 engine; no re-exported symbol is added or removed.

Fixed -- prob_floor denormal overflow -> NaN

The rescale factor was computed as sqrt(prob_floor / p(x)). A
continuous wavepacket's exponential tail underflows p(x) to deep
denormals (p ~ 1e-323), where the intermediate prob_floor / p
overflows to inf and NaN-poisons the joint renormalisation, destroying
the state on tick 0. v0.2.2 computes the algebraically identical
sqrt(prob_floor) / sqrt(p), keeping both operands in the normal
float64 range (even the smallest subnormal p ~ 1e-323 has
sqrt(p) ~ 3e-162).

Added -- floor_ledger() (A=1 cleanup budget)

Raising a sub-floor node from p up to prob_floor manufactures
(prob_floor - p) of probability; end-of-tick renormalisation
redistributes it so A=1 still holds, but the manufactured mass is a real
bookkeeping quantity. CausalSession.floor_ledger() and the floor_*
counters record it exactly. All counters stay 0 when
prob_floor is None. Quantitatively the ledger makes the cross-engine
non-equivalence visible: a small floor (1e-10-1e-6) manufactures
negligible mass; an aggressive floor (0.25) manufactures mass >> 1
and over-writes the packet toward uniform -- unlike core3d, where
sub-quantum mass rounds down to empty rather than up to the
floor.

Tests

pytest tests/ -> 257 passed, 1 skipped, 26 xfailed (v0.2.1: 252
passed). The new tests are in tests/test_prob_floor_a1_consistency.py:
TestProbFloorDenormalOverflow (a genuine deep-denormal tail stays
finite and A=1-unit over 20 ticks under np.errstate(over='raise', invalid='raise') across prob_floor in {1e-10, 1e-6, 1e-3, 0.25}, plus
split-sqrt vs fused-form agreement) and TestProbFloorLedger (zero
ledger when None; exact floor - p for a known sub-floor node;
>> 1 manufactured under an aggressive floor while A=1 holds). The 26
xfails remain pre-existing Paper~I port drift.

Installing

pip install "git+https://github.com/JackDMenendez/dcl-core@v0.2.2"

What is NOT in v0.2.2

Unchanged from v0.2.1's deferral list: GPU kernels, inter-session
coupling, complex TokenResidual carry. Out of scope for the ledger
itself: a prob_ceiling, per-edge/per-plaquette floors, and a
prob_floor on core3d (its quantum is N alone).

---

Citation. See CITATION.cff. DOI:
10.5281/zenodo.20711380.

v0.2.1 — prob_floor on the continuous engine (delta_p_min knob)

dcl_core v0.2.1 is a single-feature patch: the prob_floor
parameter on dcl_core.core.CausalSession. It exists to unblock
dcl-delta-p-min — the core column of its 4-cell grid
(exp_09_dp_min_floor) cannot run without a continuous-engine
delta_p_min knob — by giving that investigation a pinnable artifact
(dcl_core @ git+...@v0.2.1).

This is not v1.0.0. The formal API freeze remains gated on
dcl-delta-p-min finishing and co-releases with Paper III.

Semver: PATCH. prob_floor is purely opt-in and backward-compatible
— prob_floor=None (default) is bit-for-bit the v0.2.0 engine; no
re-exported symbol is added or removed.

What prob_floor does

from dcl_core.core import CausalSession
s = CausalSession(lattice, node, omega, prob_floor=1e-6)

v0.2.0 -- Cross-validation layer complete; core3d two-frame naming

dcl_core v0.2.0 closes the framework's stated v1.0 gap -- the
core <-> core3d cross-validation suite -- and lands the core3d
two-frame naming convention. We are cutting this as v0.2.0, not
v1.0.0: the public API stays under the pre-1.0 "expect breakage"
signal for one more cycle, since GPU kernels and inter-session
coupling are still ahead and may move the surface.

Semver impact: MINOR (pre-1.0). The naming retrofit renames
public symbols, but every old name still resolves through a
backward-compatible deprecation shim, so existing callers do not
break. Downstream papers pinning ==0.2.0 get a stable
reproducibility anchor.

Highlights

Cross-validation suite now passes (was 4 skipped)

All four tests/test_cross_validation.py tests pass. Each was
respec'd to the regime where the discrete (core3d) and continuous
(core) engines are actually comparable -- the two pin different
observables at fixed lattice spacing and converge only in the double
limit, so the tests assert each engine's own invariant plus a
fixed-lattice-divergence tripwire rather than a spurious shared value
(see CLAUDE.md's cross-validation triage):

• test_conservation_invariants_agree -- each engine conserves its
  own A=1 invariant.
• test_free_propagation_matches_in_large_N_limit -- core3d
  self-convergence: integer-token density tracks the continuous
  amplitude it quantises, L2 error O(sqrt(n_sites)/n_units).
• test_two_body_orbit_locks_in_both_cores (slow) -- each engine
  settles to a stable interior radius in a fixed Coulomb well.
• test_arnold_tongue_locations_agree (slow) -- single-session
  orbital resonance shows a frequency-dependent lock-in in each
  engine.

core3d two-frame naming convention

Public symbols now follow docs/design/03_naming_convention.md: the
name says what the object IS in the lattice's own mathematics, with a
# physics: comment carrying the existing-physics correspondence.
The renames (all shimmed):

• BresenhamResidual -> TokenResidual
• session state N_R/N_L/phi_R/phi_L ->
  N_RGB/N_CMY/phi_RGB/phi_CMY
• amplitude(chirality=) -> amplitude(component=) ("RGB"/"CMY")
• new BipartiteLattice.coordination, epsilon_P gains dp_min

Old names resolve today; keyword aliases emit DeprecationWarning.
Migrate before the first MAJOR after 1.0.

Reproducibility / provenance

• Pinned-dependency Dockerfile + tracked .vscode/extensions.txt.
• docs/data_deposit_and_provenance.md -- per-experiment provenance
  manifests, one Zenodo dataset record per paper, heavy data
  deposited (not bundled into the software DOI).
• Release protocol v2 adopted in release_notes/README.md.

Tests

pytest tests/ reports 232 passed, 26 xfailed, 0 skipped
(v0.1.0: 228 passed, 4 skipped, 26 xfailed). The 26 xfails remain
pre-existing Paper~I port drift (documented in CLAUDE.md).

Installing

pip install "git+https://github.com/JackDMenendez/dcl-core@v0.2.0"

For symbolic-verification tests (Clifford algebra) or GPU backend:

pip install "dcl_core[sympy] @ git+https://github.com/JackDMenendez/dcl-core@v0.2.0"
pip install "dcl_core[gpu]   @ git+https://github.com/JackDMenendez/dcl-core@v0.2.0"

What is NOT in v0.2.0

Still ahead (unchanged from v0.1.0's deferral list):

• GPU backend kernels (allocators wired; RawKernel bodies pending).
• Pairwise multi-session interactions (Coulomb / gauge / emission);
  the richer two-session Arnold-tongue needs these.
• Complex TokenResidual carry -- real carry only; the complex-carry
  hypothesis is parked for Paper~III's min-Δp experiments
  (notes/bresenham_residual_design.md).

---

Citation. See CITATION.cff. Zenodo DOI for this release:
10.5281/zenodo.20586191.

v0.1.0 -- First citable release: integer-token engine + Paper I continuous port

v0.1.0 -- First citable release: integer-token engine + Paper I continuous port

dcl_core v0.1.0 is the first Zenodo-deposited release of the core
library underlying the A=1 Discrete Causal Lattice framework. The
package ships two engines side-by-side: dcl_core.core
(continuous-amplitude, ported verbatim from Paper I) and
dcl_core.core3d (integer-token, the new design). Their
coexistence is deliberate -- Paper III's discrete-vs-continuous
probability comparison uses both -- and is documented as a
project-level decision in MEMORY.md.

Semver impact: MINOR. Pre-1.0 (0.X.Y) signals "API still
unstable"; downstream papers pinning to ==0.1.0 get a stable
reproducibility anchor, but consumers tracking main should
expect minor bumps to break them.

Why this is v0.1.0 and not 0.1.0-dev

0.1.0-dev was the template state with NotImplementedError stubs
everywhere in core3d. v0.1.0 closes that out: every public method
of every core3d class is implemented and tested, A=1 conservation
holds as an exact integer identity across 1000-tick runs, and the
public API surface in __init__.py is what downstream papers
should plan against.

Highlights

Public-API surface

• dcl_core.core -- continuous-amplitude engine (Paper I port).
  OctahedralLattice, CausalSession, CompositeCausalSession,
  TickScheduler, PhaseOscillator, UnityConstraint.
• dcl_core.core3d -- integer-token engine (new design).
  BipartiteLattice, DiscreteCausalSession (with delta_at,
  wavepacket, from_arrays factories), BresenhamResidual,
  HopOperator, TickScheduler.
• dcl_core.core3d.clifford -- opt-in Dirac gamma matrices
  (gamma_0..gamma_3, ETA_MINKOWSKI, GAMMAS). Sympy is
  lazy-imported; the module is safe to load without the
  [sympy] extra.

New capabilities

• A=1 by integer arithmetic. sum(N(x)) == n_units exactly
  at every tick, with no float renormalisation. The
  BresenhamResidual floor + global top-up rebalance is what
  enforces this -- see the docstring algorithm for the details.
• Min-Δp wavepacket factory. DiscreteCausalSession.wavepacket( ..., sigma=...) is the minimum-uncertainty Gaussian; Δp = 1 / (2 σ_x). Paper III's min-Δp scan is a for sigma in [...]
  loop over this factory.
• Two-engine cross-validation harness. tests/test_cross_validation.py
  exposes the discrete-vs-continuous comparison surface
  (free-particle wavepacket convergence, two-body Bohr orbit,
  conservation parity, Arnold-tongue frequency-locking). The
  test bodies are stubbed pending Paper III's experimental
  setup but the spec is in place.

Tooling / internals

• experiments/exp_01_throughput.py -- tick-throughput sweep
  across lattice shapes; outputs structured .npy + JSON sidecar.
• experiments/exp_02_phase_profile.py -- cProfile breakdown of
  one tick at a fixed shape.
• tools/diff_baselines.py -- compares two exp_01_throughput
  baselines, prints per-shape speedup ratios. Designed for the
  pre-/post-hardware-upgrade comparison.
• on_tick_complete callback on TickScheduler -- third-party
  instrumentation hook (Paper III's experiments hang timing /
  observable extraction off it).

Tests

pytest tests/ reports 228 passed, 4 skipped, 26 xfailed. The
4 skips are cross-validation tests whose bodies live downstream.
The 26 xfails are pre-existing Paper I drift inherited verbatim with
the port (documented in CLAUDE.md).

Installing

pip install dcl_core==0.1.0

For symbolic-verification tests (Clifford algebra) and GPU backend:

pip install "dcl_core[sympy]==0.1.0"
pip install "dcl_core[gpu]==0.1.0"   # requires CUDA + CuPy build

For the pre-PyPI / GitHub-pinned install (which downstream papers
should use until PyPI publication):

pip install "git+https://github.com/JackDMenendez/dcl-core@v0.1.0"

What is NOT in v0.1.0

• GPU backend kernels (allocators wired, RawKernel bodies
  pending v0.2.0).
• Pairwise multi-session interactions (Coulomb / gauge coupling /
  emission pairs).
• Complex BresenhamResidual.carry -- the parked hypothesis
  that the residual should be a virtual-particle amplitude tied
  to the 51 extra generators in Paper II's algebra. The
  determination is expected to live downstream in Paper III's
  min-Δp experiments; the v0.1.0 carry is real as a known
  placeholder.

Full roadmap: see CLAUDE.md (CURRENT STATUS) and
notes/bresenham_residual_design.md.

---

Citation. See CITATION.cff. Zenodo DOI for this release:
10.5281/zenodo.20350952.