Stage 1: behavior-preserving construction for cellpy 2 (tracking issue)

[jepegit]

Goal

Complete Stage 1 — behavior-preserving construction: every refactor and parallel
build that can land on master with the full v1.x suite green, so that the Stage-2 flip
(native headers + polars, one flag-day) becomes a small, well-oracled step instead of a
rewrite. Nothing in Stage 1 changes user-visible behavior; everything is guarded by the
Stage-0 characterization suites and oracles (#439).

Why

The plans in cellpy-workspace/architecture-plan/ (the architecture-plan repo; formerly architecture-plan/) are all shaped around the same move:
build the new thing next to the old thing, prove parity, then swap. Stage 1 is the
"build next to" phase across five workstreams: cellpy-file I/O, configuration, units,
header translation, and de-indexing — plus the additive cellpy-core modules
(units helpers, mapping extensions, meta mapping, curves) they consume.

Issues by workstream

cellpy-file I/O (architecture-plan/cellpy-file-loading-refactor-plan.md)

• Stage 1.1: Purge non-config constants from prms.py; create readers/cellpy_file/ with format.py #446 — Stage 1.1: constants purge + cellpy_file/format.py (shared with config plan)
• Stage 1.2: File-loading — stateless helpers out, selector/limits side-channel dead #447 — Stage 1.2: stateless helpers + selector/limits de-stating
• Stage 1.3: File-loading — move the read and write paths into cellpy_file/ #448 — Stage 1.3: read + write paths move into cellpy_file/
• Stage 1.4: File-loading — out-of-band redirects, typed errors, cellpy convert CLI #449 — Stage 1.4: out-of-band redirects, typed errors, cellpy convert CLI

Units (architecture-plan/unit-handling-cellpy2-plan.md)

• Stage 1.5: Units Phase 1 — one CellpyUnits, one pint registry, rename the core alias #450 — Stage 1.5: one spec, one registry, rename the core alias
• Stage 1.13: units — convert_value, calculate_scaler, validate_units cellpy/cellpy-core#115 — Stage 1.13: convert_value, calculate_scaler, validate_units
• Stage 1.6: Units Phase 2 — delegate the duplicated converters to cellpycore.units #451 — Stage 1.6: delegate the duplicated converters

Configuration (architecture-plan/cellpy2-configuration-and-parameters-plan.md)

• Stage 1.7: Config — build the pydantic-settings stack in parallel #452 — Stage 1.7: pydantic-settings stack built in parallel
• Stage 1.8: Config — swap the engine under prms, migrate call sites, kill import-time init #453 — Stage 1.8: prms shim swap, call-site migration, no import-time init
• Stage 1.9: Config — cellpy setup rewrite and migration UX #454 — Stage 1.9: cellpy setup rewrite + migrate UX

Headers (architecture-plan/cellpy2-native-headers-migration-plan.md)

• Stage 1.10: Fix hard-coded column-header literals (report priorities 1–3) #455 — Stage 1.10: hard-coded header-literal cleanup (priorities 1–3)
• Stage 1.14: legacy mapping extensions — postfix expansion + attribute-level table cellpy/cellpy-core#116 — Stage 1.14: mapping extensions (postfix expansion + attribute table)
• Stage 1.15: translate.py — dormant native⇄legacy frame translation in cellpy_file/ #458 — Stage 1.15: dormant translate.py (to_native/to_legacy) + bridge extraction

Polars preparation (architecture-plan/cellpy2-polars-port-execution-plan.md)

• Stage 1.12: Polars Phase A — de-index raw/summary/journal in place #457 — Stage 1.12: Phase A de-indexing (raw/summary/journal) + warn-only lint

Conventions

• Stage 1.11: Conventions machinery — deprecation helper, exception tree (implementation) #456 — Stage 1.11: deprecation helper + exception tree (implementation of Stage 0.10: Conventions bootstrap — deprecation helper, exception tree, DEPRECATIONS registry #437)

cellpy-core additive modules

• Stage 1.16: metadata — legacy⇄core field-mapping module (meta_mapping) cellpy/cellpy-core#117 — Stage 1.16: legacy⇄core metadata field mapping (+ G9/volume decisions)
• Stage 1.17: cellpycore.curves — spec'd capacity/OCV curve extraction cellpy/cellpy-core#118 — Stage 1.17: cellpycore.curves (spec'd extraction layer; gated on Stage 0.11: Decision register — the calls that gate Stage 1+ #438 decision 2)

Sequencing constraints (the ones that bite)

1. Stage 1.5: Units Phase 1 — one CellpyUnits, one pint registry, rename the core alias #450 before Stage 1.2: File-loading — stateless helpers out, selector/limits side-channel dead #447/Stage 1.3: File-loading — move the read and write paths into cellpy_file/ #448 — the core-alias rename must not interleave with the
   cellreader code moves (agreed in both plans' risk tables).
2. Core-first merge order for additions: Update pyyaml to 3.13 #115 → release + re-pin → Stage 1.6: Units Phase 2 — delegate the duplicated converters to cellpycore.units #451;
   Update pytest to 3.7.1 #116 → release + re-pin → Stage 1.15: translate.py — dormant native⇄legacy frame translation in cellpy_file/ #458 (release plan §3).
3. Stage 1.11: Conventions machinery — deprecation helper, exception tree (implementation) #456 before Stage 1.4: File-loading — out-of-band redirects, typed errors, cellpy convert CLI #449 and Stage 1.8: Config — swap the engine under prms, migrate call sites, kill import-time init #453 (they import the conventions machinery).
4. Stage 0.9: Benchmark harness + v1.x performance baselines #436 baselines before Stage 1.12: Polars Phase A — de-index raw/summary/journal in place #457 (de-indexing is where perf could silently move).
5. Stage 1.1: Purge non-config constants from prms.py; create readers/cellpy_file/ with format.py #446 is the shared step of two plans — whoever lands it, the other rebases.
6. Stage 1.10: Fix hard-coded column-header literals (report priorities 1–3) #455 and Stage 1.7: Config — build the pydantic-settings stack in parallel #452 are independent and can start immediately.

Exit criteria (Stage 1 done ⇒ Stage 2 flip may be scheduled)

• All Stage-0 characterization suites still green, unmodified except where a change is
  deliberate and documented (typed errors in Stage 1.4: File-loading — out-of-band redirects, typed errors, cellpy convert CLI #449, config divergences in Stage 1.7: Config — build the pydantic-settings stack in parallel #452).
• cellpy_file/ owns all cellpy-file I/O; CellpyCell.load/save are thin wrappers.
• One pint registry (interop test hard-passes); no duplicated converter bodies.
• Config: no import-time I/O; parity contract green; old conf migrates.
• translate.py round-trip (v8 → native → v8) green; value-parity comparator (Stage 0.7: Value-parity comparator — the mapped-columns oracle harness #434)
  green against the bridge.
• De-indexing done; benchmarks (Stage 0.9: Benchmark harness + v1.x performance baselines #436) within band vs the v1.x baselines.
• Core releases tagged and re-pinned for Update pyyaml to 3.13 #115/Update pytest to 3.7.1 #116/Update flake8 to 3.5.0 #117/Update coverage to 4.5.1 #118.
• Behavior-delta sign-off (added 2026-07-14): every observed 1.0.3 → 1.0.4a3
  behavior delta is either confirmed intended (release-noted + named exception in
  the Stage 0.7: Value-parity comparator — the mapped-columns oracle harness #434 comparator) or fixed as a regression — CE inversion, coulombic-difference
  sign flip, dropped shifted_* specific / reference_voltage_* columns, cv_charge
  step fix, sub_type null change, and the discharge_c_rate legacy-vs-core engine
  mismatch (must be explained, not excepted). Register with verdicts:
  architecture plan §7;
  source: cellpy-v103-vs-v104a3-observations.md.
  This criterion specifically gates the final v1.x release (ship gate: architecture
  plan §6.1); core#117/Update coverage to 4.5.1 #118 remain Stage-1 exit items but do not gate that release.

[jepegit]

Exit criteria updated (2026-07-14): added the behavior-delta sign-off criterion — the observed 1.0.3 → 1.0.4a3 deltas (CE inversion, coulombic sign flip, dropped columns, discharge_c_rate engine mismatch, etc.) must each be confirmed intended or fixed before the final v1.x release. Register with per-delta verdicts: architecture plan §7; ship gate for the final legacy release: §6.1 of the same document.

[jepegit]

Stage-1 issue set complete (2026-07-15). All nine remaining work items closed today, each via its own suite-green PR:

• cellpy-core (released as cellpycore 0.2.0 on PyPI, re-pinned in cellpy): Update pyyaml to 3.13 #115 units helpers (PR feat(units): convert_value, calculate_scaler, validate_units (Stage 1.13, #115) cellpy/cellpy-core#123) · Update pytest to 3.7.1 #116 mapping extensions (PR dqdv histogram method #124) · Update flake8 to 3.5.0 #117 meta_mapping + G9/volume decisions (PR A more complete set of files for testing #125) · Update coverage to 4.5.1 #118 cellpycore.curves with rtol-1e-9 parity vs the Stage 0.6: Curve-extraction golden snapshots (get_cap family) #433 snapshots (PR Update numpy to 1.16.3 #126)
• cellpy: Stage 1.6: Units Phase 2 — delegate the duplicated converters to cellpycore.units #451 converter delegation + 0.2.0 re-pin (PR feat(units): delegate duplicated converters to cellpycore.units (Stage 1.6, #451) #497, also fixed three M2 leftovers incl. the log.setup_logging config shadowing that caused the order-dependent test failures) · Stage 1.8: Config — swap the engine under prms, migrate call sites, kill import-time init #453 closed after M1–M3 merged (PRs Stage 1.8 M1: prms shim + legacy YAML load path (#453) #494–Stage 1.8 M3: remove import-time config init (#453) #496) · Stage 1.9: Config — cellpy setup rewrite and migration UX #454 setup TOML twin + setup migrate + info --config (PR feat(cli): setup writes cellpy.toml twin; setup migrate; info --config (Stage 1.9, #454) #498) · Stage 1.12: Polars Phase A — de-index raw/summary/journal in place #457 Phase-A de-indexing + warn-only index lint, benchmark gate green (PR feat(frames): Polars Phase A — de-index raw/summary/journal + warn-only lint (Stage 1.12, #457) #499) · Stage 1.15: translate.py — dormant native⇄legacy frame translation in cellpy_file/ #458 dormant translate.py, v8→native→v8 round-trip exact, Stage 0.7: Value-parity comparator — the mapped-columns oracle harness #434 comparator green (PR feat(cellpy_file): dormant native⇄legacy frame translation (Stage 1.15, #458) #500)

Exit criteria: all technical criteria are met (cellpy_file owns all I/O ✅ · one registry, no duplicated converters ✅ · config free of import-time I/O ✅ · translate round-trip + comparator ✅ · de-indexing with benchmarks in band ✅ · core released + re-pinned ✅). The one remaining criterion is the behavior-delta sign-off (architecture plan §7 — CE inversion, coulombic sign flip, dropped columns, discharge_c_rate engine mismatch): maintainer decisions, gating the final v1.x release per architecture plan §6.1. Leaving this tracking issue open for that sign-off.