[vistart]

Description

This PR aligns python-activerecord-firebird with the new semantic error taxonomy and execute-phase contract:

• Recognises SQLSTATE first: 23000/23505 unique, 22004 not-null, 40001 update conflict/deadlock, -901/-902 lock conflicts, 08006/08001 connection loss, 28000 auth, 42xxx query errors.
• execute / execute_many / executescript preserve framework errors, map raw drivers, and cannot return None; auto-commit failures raise TransactionError.
• Firebird remains synchronous-only; removing its async backend family is deferred to feature/firebird-sync-only.

Adds # (no issue)

Type of change

• feat: A new feature
• test: Adding missing tests or correcting existing tests (for the new feature)
• docs: Documentation only changes (if related to the new feature)
• perf: A code change that improves performance (if part of the feature)
• chore: Changes to the build process or auxiliary tools and libraries suchs as documentation generation (if related to the new feature)
• ci: Changes to our CI configuration files and scripts (if related to the new feature)
• build: Changes that affect the build system or external dependencies (if related to the new feature)
• revert: Reverts a previous commit

Breaking Change

• Yes, for end-users (backward-incompatible API changes)
• Yes, for backend developers (internal architectural changes that may affect custom implementations)
• No breaking changes

Impact on End-Users:
No backward-incompatible changes: concrete error classes keep their names, and every error remains a DatabaseError. Behavioural change: auto-commit failures now raise TransactionError instead of being logged and ignored, and transient connection retries now actually run.

Impact on Backend Developers (Custom Implementations):
No signature changes. Custom _handle_error implementations should raise taxonomy errors; the core pipeline adds a defensive fallback when a handler returns.

Related Repositories/Packages

• python-activerecord PR #139.
• python-activerecord-testsuite PR (taxonomy contract).
• CI pins in this repository currently point at feature/error-taxonomy for both core and testsuite, and will be restored to release branches after the merge.

Testing

• I have added new tests to cover my changes.
• I have updated existing tests to reflect my changes.
• All existing tests pass.
• This change has been tested against the backend matrix via CI.

Test Plan:

Local contract suites: 45 passed. Feature-branch CI run 42973530733: success.

Reproduction:

PYTHONPATH=src:tests pytest tests -k 'test_execute_error_contract or test_driver_error_mapping or test_error_taxonomy_contract'

Checklist

• My code follows the project's code style guidelines.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation (Docstrings, README.md, etc.).
• My changes generate no new warnings.
• I have added a Changelog fragment (changelog.d/<issue_number>.<type>.md).
• I have verified that my changes do not introduce SQL injection vulnerabilities.
• I have checked for potential performance regressions.

Additional Notes

• The changelog fragment is added as changelog.d/<PR>.added.md once the PR number exists, because the checker requires the fragment number to equal the PR number.
• CI intentionally installs core and testsuite from feature/error-taxonomy; restore release pins after this PR and the core PR merge.

[codecov]

Codecov Report

❌ Patch coverage is 88.75000% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.16%. Comparing base (c65ad02) to head (1f5576d).

Files with missing lines	Patch %	Lines
...ord/backend/impl/firebird/backend/async_backend.py	68.57%	10 Missing and 1 partial ⚠️
...cord/backend/impl/firebird/mixins/backend_mixin.py	96.42%	0 Missing and 4 partials ⚠️
...iverecord/backend/impl/firebird/backend/backend.py	76.92%	3 Missing ⚠️

Additional details and impacted files

@@                   Coverage Diff                   @@
##           release/v1.0.0.dev2      #14      +/-   ##
=======================================================
+ Coverage                78.65%   79.16%   +0.51%     
=======================================================
  Files                       99       99              
  Lines                     7130     7233     +103     
  Branches                  1093     1117      +24     
=======================================================
+ Hits                      5608     5726     +118     
+ Misses                    1236     1227       -9     
+ Partials                   286      280       -6     

Flag	Coverage Δ
firebird-6-snapshot	79.16% <88.75%> (+0.51%)	⬆️
python-3.14	79.16% <88.75%> (+0.51%)	⬆️
unittests	79.16% <88.75%> (+0.51%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
9 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud