[AdamCorrao]

re/02 — gateway registry + shared core modules (G1 gate branch)

This branch doesn't change behaviour. powderline.run(recipe, output_dir, engine=...) works exactly as before, with the same engine= names, schema 0.26.0 and outputs. The difference is that dispatch now goes through a plugin registry. The branch also adds the shared core modules that the schema branches (re/03–06) build on. G1 gate: passed (independent reviewer session, no blockers); the review's findings are fixed in this branch.

What's in it

• Gateway registry (powderline.registry)
  • Discovers gateways lazily from the powderline.gateways entry-point group: ep.load() runs only when a gateway is first requested.
  • register_gateway() escape hatch for tests and development.
  • GatewayNotInstalledError, plus a clear "re-install" error when no entry points are found at all.
  • Contract: a frozen Gateway dataclass (A54).
• Engine-free gateway factories: gateways/gsasii/gateway.py, topas/gateway.py, easydiff/gateway.py.
  • Schema layer (validate, capabilities): runs with no engine installed.
  • Runtime layer (run): thin wrappers over today's kicker.run / run_topas_recipe / run_easydiffraction_recipe, importing the engine lazily.
  • Version check: a real run checks the installed engine version against ENGINE_VERSION_SPEC and fails hard if it's out of range (EngineVersionError, A44). Specs: GSAS-II ==5.7.9, TOPAS >=7,<8, easydiffraction >=0.20.1,<0.21. There's a test-only bypass, allow_unsupported_engine_version (A53).
  • Missing engine: raises EngineNotAvailableError, which is also an ImportError, so existing except ImportError code keeps working (A52).
  • Uniform contract: every gateway has validate(recipe, *, verbose=False) (A50, A59).
• Dispatcher (powderline.engine.run) maps the old engine= names 1:1 to registry names. Its public signature is unchanged.
• symmetry promoted from topas/ to core powderline.symmetry, ending the easydiff → topas import. The move is verbatim except for one thing: the error is created by a lazy _translation_error() helper, because a top-level import would be circular. This is a temporary fix; re/03 replaces it with a core error (A56/A57).
• New core modules, created and unit-tested only (gateways start using them in re/04–06):
  • exceptions.py: the error types plus the {code, message, field_path} warning shape (A60 confirms RecipeValidationError subclasses ValueError).
  • fitstats.py: Rwp and Rexp in percent, GoF and reduced χ² unitless. N counts only in-range points with weight > 0; P is the parameter count reported by the engine (A41, A45, A55).
  • reports.py: shared writers for the four standard report files. They reproduce all 37 committed GSAS-II references byte for byte.
• Moved verbatim: validate + validate_simulation_mode_parameters now live in an engine-free gateways/gsasii/validation.py; kicker re-exports both (A51).
• Packaging:
  • [project.entry-points."powderline.gateways"] added.
  • packaging>=22 declared in pyproject + pixi.toml. The pixi.lock diff is a single requires_dist line.
  • CLAUDE.md notes that pixi reinstall powderline is needed after editing entry points.
• known_issues.md KI-13 (watch): every engine, including the default gsasii, now depends on entry-point metadata written at install time. We keep entry points as the only discovery path (A58).

Commits (10 on ae415c8)

SHA	Subject
fe49fd0	feat(core): add the exceptions module and structured-warning shape
b9767a7	refactor(gsasii): move validate + validate_simulation_mode_parameters to an engine-free module (verbatim)
b3eec02	refactor(core): promote symmetry out of topas/ into powderline.symmetry
a42a8a7	feat(core): add fitstats — uniform Rwp, Rexp, GoF, reduced chi-squared
9c24109	feat(core): add reports — shared writers for the standardized report files
8d98e6d	feat(core): gateway registry + engine-free gateway factories; dispatcher routed through it
4e1bc1b	fix(core): route every symmetry raise through one lazy error helper (G1 KI-13)
04b1368	fix(core): fitstats rejects non-finite weights inside the fit range (G1 nit)
33f510c	fix(gateways): uniform validate(recipe, *, verbose=False) contract; test hygiene (G1 nits)
a84fd39	docs(known_issues): KI-13 — engine dispatch depends on entry-point metadata (watch)

Verification

• Default env: 498 passed / 3 skipped at ae415c8 → 637 passed / 4 skipped at a84fd39.
  • Every baseline test has the same outcome.
  • +139 new tests.
  • The +1 skip is a test that only runs when easydiffraction is installed.
• easydiff env: the pre-existing test_easydiff_* give 54 passed, unchanged. Run with the new registry, gateway, symmetry and fitstats tests: 152 passed / 2 skipped.
• Unchanged outputs: run(engine="gsasii") and run(engine="topas") on LaB6 produce byte-identical outputs at ae415c8 and on this branch. GSAS-II also matches the committed references within regression-tolerance.
• Freeze: no hashed GSAS-II module touched; _code_hash.json unchanged. examples/ untouched.
• No engine imports in core: a subprocess test blocks GSAS-II and easydiffraction, then validates through the registry for all three gateways.
• No undefined names: a new undefined-name probe finds none across all 27 source modules changed since v0.1.1.
• Encoding: UTF-8 + LF on every touched file.

G1 gate

An independent reviewer session gave PASS on every checklist item (evidence reproduced, not taken on trust). Findings were resolved on this branch with the maintainer (A57–A60):

• Two raise sites in symmetry.py would have hit NameError on unreachable paths (a regression from
  An independent reviewer session gave PASS on every checklist item (evidence reproduced, not taken on trust). Findings were resolved on this branch with the maintainer (A57–A60):
• Two raise sites in symmetry.py would have hit NameError on unreachable paths (a regression from the move). Fixed before merge.
• The entry-point dependence is filed as KI-13 (watch).
• Four nits fixed.

Evidence: devkit dossiers/multi-engine/tasks/re02-g1-record.md.

Obligations for later branches

• re/03: replace the symmetry _translation_error() helper with a core error that each gateway translates into its own type (a deliberate behaviour change for the A34 table). Keep A59's validate contract.
• re/04–06: gateways return their own schema models from validate(), adopt fitstats/reports, and supply P for fitstats.
• re/08: env names and pins mirror each ENGINE_VERSION_SPEC; add install-health guidance for KI-13.
• re/09: wire allow_unsupported_engine_version into the compatibility suite.

Decisions: master plan §3 A50–A60. Devkit record commits: 72a319c, c31768d, 0b8cd50.

🤖 Generated with Claude Code