Paxman 1.0.2 released — 7 v1.0.x hotfixes

[azaharizaman]

Paxman 1.0.2 released — 7 v1.0.x hotfixes

Paxman 1.0.2 is now available on PyPI: pip install paxman==1.0.2

What is it

A patch release addressing all 7 open bugs filed against v1.0.0 in the v1.0.x milestone. Safe to upgrade for any v1.0.0 or v1.0.1 caller — no breaking changes, no new dependencies, no public API removals.

Why a release before Friday

The v1.0.x milestone description said patches are released every Friday. We deviated this once because the release is purely additive (no docs other than the release notes themselves, no migrations, no behavior changes for callers who did not trigger the bug paths). Friday cadence is a process preference, not a correctness one. The trade-off: bug-fix users get the fixes ~36 hours earlier. We will return to Friday cadence for v1.0.3 and beyond.

What is fixed

#	Severity	Summary
#58	medium	Pydantic adapter: Optional[Annotated[T, ...]] is now accepted (was UNSUPPORTED_FIELD_TYPE).
#59	medium	Public register_capability() / register_adapter() now accept replace: bool = False.
#60	medium	capability_versions is now derived from the reconciled evidence (single source of truth).
#61	medium	Pydantic float → DECIMAL conflation is now documented loudly.
#62	low	_is_optional() uses types.UnionType identity, not a fragile __name__ check.
#64	low	Reconciler no longer imports the private _check_constraint from paxman.capabilities.v1.validation.
T3 follow-up	—	V1 lookup self-registration bootstrap fix (regression caught by golden-artifact tests after the #64 fix).

Plus a separate commit for each of:

• Format pass (make format)
• CHANGELOG + release notes
• Version bump 1.0.1 → 1.0.2
• Oracle review follow-ups (stale cross-references, bootstrap regression test)
• CodeRabbit review fixes (changelog wording, bootstrap docstring, ImportError logging, test correctness)

Who should upgrade

Everyone. v1.0.2 is a safe drop-in. Especially recommended if you:

• Use Optional[Annotated[T, Field(...)]] in Pydantic contracts ([bug] Pydantic adapter drops inner type for Union[Annotated[T, ...], None] #58)
• Hot-reload capabilities or adapters during development ([bug] Public register_capability/register_adapter don't expose replace=True #59)
• Replay artifacts that were normalized with a capability that has multiple versions ([bug] capability_versions collected from wrong evidence set + last-write-wins #60)
• Use float for non-money numeric fields in Pydantic contracts ([bug] Pydantic float annotation is silently mapped to DECIMAL (money-like) #61)
• Maintain a fork of Paxman that touches the reconciler/capabilities boundary ([bug] reconciler/validation.py imports private _check_constraint from capabilities.v1 #64)

What is not fixed

These are tracked for V2 and out of scope for a v1.0.x bugfix:

• A proper FLOAT field type ([bug] Pydantic float annotation is silently mapped to DECIMAL (money-like) #61 Option B). Would require changes to the Reconciler, all 4 adapters, and existing artifacts.
• The DiagnosticCode enum remains a closed V1 set; [bug] capability_versions collected from wrong evidence set + last-write-wins #60's conflict warning uses structlog rather than a new DiagnosticCode value. Adding a new code requires an ADR.
• ReDoS risk on caller-supplied PATTERN regex (pre-existing in v1.0.1; would need regex-complexity guards)
• Unguarded numeric coercion in constraint params (pre-existing in v1.0.1; would need defensive try/except)

Upgrade guide

pip install --upgrade paxman==1.0.2

No code changes required for v1.0.0 / v1.0.1 callers. If you imported the private helper _check_constraint from paxman.capabilities.v1.validation in your own code, it still works via the re-export shim — but you should switch to the new canonical location paxman.validation.constraints.check_constraint.

Links

• Full release notes: docs/concepts/RELEASE_NOTES_v1.0.2.md
• Changelog: docs/operations/changelog.md
• PR: #87
• PyPI: paxman 1.0.2

Thanks to everyone who reported, triaged, and reviewed these bugs. The bug reports themselves were exceptionally high quality — each included a minimal reproducer, a root-cause analysis, and a recommended fix option. The fixes are largely mechanical translations of those recommendations.

— The Paxman maintainers