feat: workspace version check — compatibility floor + staleness warning (R2)

[Jammy2211]

Overview

R2 of the version-pinning design review (PyAutoLabs/PyAutoHands#118). check_version() currently raises WorkspaceVersionMismatchError on exact inequality between installed library and workspace-recorded version — maximally brittle under the reinstated daily release cadence, and its advice can tell users to pin-install yanked versions. This task replaces exact-match with a compatibility floor: raise only when the installed library is older than what the workspace requires; warn (never raise) when the workspace clone looks stale.

Autonomy: --auto, effective supervised (feature cap). Plan recorded here; run proceeds; ship sign-off will park with a batched question per the contract.

Plan

• Workspace records version.minimum_library_version in config/general.yaml; check becomes installed >= minimum.
• Legacy records (version.workspace_version, version.txt) are reinterpreted as floors — the common "old clone, newer library" case passes instead of hard-failing.
• Add a staleness warning (never an exception) when the installed library is >30 days newer than the recorded floor.
• Rewrite advice text: never recommend exact == pins (may be yanked); recommend plain upgrade / git pull / the existing bypasses.
• Keep both bypasses and cwd-based discovery; extend test_autoconf for the new semantics.

Detailed implementation plan

Affected Repositories

• PyAutoConf (primary; downstream libraries call check_version on import but its signature is unchanged)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoConf	main	clean

Suggested branch: feature/version-check-compat-floor
Worktree root: ~/Code/PyAutoLabs-wt/version-check-compat-floor/

Implementation Steps

1. autoconf/workspace.py:
   • Resolve the floor with precedence version.minimum_library_version → version.workspace_version → version.txt.
   • _parse_version date-tuple comparison: raise WorkspaceVersionMismatchError only when installed < floor; unparseable versions (dev installs, arbitrary strings) fall back to a warning on inequality, never a raise.
   • Staleness path: both versions parseable and installed's (Y, M, D) date is >30 days after floor's → warnings.warn advising git pull (and floor-bump if deliberate).
   • New advice text: pip install --upgrade <library> (no == pin anywhere), git pull origin main, bypass instructions unchanged; keep the directional logic from PyAutoConf#107 but floor-aware.
2. test_autoconf/test_workspace.py (or the existing test module): cover — floor satisfied (equal / newer installed), installed below floor (raises), legacy exact key as floor, staleness warning >30 days, unparseable version warn-not-raise, both bypasses, missing records warning. numpy-only, no JAX.
3. Full suite python -m pytest test_autoconf/.

Key Files

• PyAutoConf/autoconf/workspace.py — check_version, _mismatch_message, _parse_version
• PyAutoConf/test_autoconf/ — new/extended workspace-check tests

Out of scope (follow-ups)

• Workspace general.yaml adoption of minimum_library_version (workspace task after this ships).
• Release-pipeline changes to stop writing workspace versions (R3, PyAutoBuild).

Original Prompt

Click to expand starting prompt

R2 of PyAutoBuild#118 (endorsed 2026-07-08): make the workspace check a compatibility window, not equality — workspace records a minimum required library version (bumped deliberately, only when scripts start depending on new API — not by the release cron), check installed >= minimum, and warn (never raise) when the library is much newer than the workspace clone (e.g. >30 days by date-version comparison). This preserves the wrong-pairing protection while eliminating the daily-mismatch storm and removing the release pipeline's need to touch workspace repos at all.

User go-ahead: "ok, those PRs are done so we can do this work now --auto"

[Jammy2211]

Ship sign-off (supervised --auto: parked here, uncommitted in the worktree)

Implementation complete and validated. Answerable cold:

What changed

autoconf/workspace.py — check_version() now enforces a compatibility floor instead of exact equality:

• Floor precedence: version.minimum_library_version (new key) → version.workspace_version (legacy, reinterpreted as floor) → version.txt.
• installed < floor → WorkspaceVersionMismatchError (unchanged protection: scripts may need API the install lacks).
• installed >= floor → passes; if >30 days newer (date comparison) → warning advising git pull — the previously-fatal "old clone, newer library" case now works.
• Unparseable versions (e.g. 1.0.dev0 dev installs) → warn on inequality, never raise.
• Advice text contains no == pins anywhere (no more recommending yanked versions); below-floor advice covers the unreleased-main case via workspace release tags.
• Both bypasses, cwd discovery, and the public signature are unchanged.

test_autoconf/test_workspace.py — +7 tests for the new semantics (floor pass/raise, key precedence, staleness window, unparseable both directions, no-pin advice).

API Changes

• Behavioral, not structural: check_version(library_version, workspace_root=None) signature and WorkspaceVersionMismatchError unchanged; downstream check_version(__version__) import-time calls in autofit/autogalaxy/autolens need no edits.
• New optional workspace config key version.minimum_library_version (adoption is the workspace follow-up task).
• Semantics loosened in one direction only: cases that previously raised (installed newer than record) now pass or warn.

Validation

• test_autoconf/ full suite: 117 passed (20 workspace-check tests, 7 new). The one -W error failure is pre-existing hygiene in test_test_mode.py (return-not-None), untouched.
• Real-world scenario probe: today's broken new-user case still correctly raises (fix is the R1 release); old-clone/newer-library passes silently; 60-day gap warns git pull once.

Heart

YELLOW (score 42): workspace validation not passing (5 failed) / 58 stale parked scripts / autolens_assistant pinned behind / install verification not run / no release validation for current source / PyAutoMind open PR 9d old. No launch-time ack covers these → parked per the contract.

On approval

Commit on feature/version-check-compat-floor (worktree), push, open a pending-release PR to PyAutoConf main. Downstream ripple: none until workspaces adopt the new key. Follow-ups queued: workspace general.yaml adoption task; R3 (PyAutoBuild stamping) proceeds independently meanwhile.

Answer options: (a) "ship it" — I commit/push/open the PR with the Heart YELLOW reasons above acknowledged; (b) request changes; (c) hold.

[Jammy2211]

Shipped at PR-open: #119 (commit 452f0f7, 117 tests pass, labeled pending-release). Maintainer sign-off + Heart YELLOW acknowledgement (the 6-reason set listed in the sign-off comment above) given in-session 2026-07-08 via "continue --auto" after the sign-off summary was surfaced. Merge is yours; PyAutoBuild#121 is merge-gated behind this PR.

[Jammy2211]

Merged as #119 (2026-07-08). The compatibility-floor check ships with the next release; workspace adoption of version.minimum_library_version is the queued follow-up.