[vistart]

Description

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

• Maps duplicate/not-null to IntegrityError, login to non-transient ConnectionError, timeouts/service failures to transient OperationalError, syntax/unknown identifiers to QueryError, permission denials to non-transient DatabaseError.
• Framework errors short-circuit before classification.
• Snowflake has no lock/deadlock semantics; no LockError/DeadlockError is invented.

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: 49 passed. Feature-branch CI run 42973514422: 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.

[sonarqubecloud]

Quality Gate passed

Issues
23 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

[codecov]

Codecov Report

❌ Patch coverage is 94.18605% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.96%. Comparing base (67c1054) to head (20cb209).

Files with missing lines	Patch %	Lines
...iverecord/backend/impl/snowflake/mixins/backend.py	94.04%	2 Missing and 3 partials ⚠️

Additional details and impacted files

@@                   Coverage Diff                   @@
##           release/v1.0.0.dev2      #12      +/-   ##
=======================================================
+ Coverage                80.92%   80.96%   +0.04%     
=======================================================
  Files                      118      118              
  Lines                     5694     5733      +39     
  Branches                   829      841      +12     
=======================================================
+ Hits                      4608     4642      +34     
- Misses                     838      840       +2     
- Partials                   248      251       +3     

Flag	Coverage Δ
python-3.12	80.96% <94.18%> (+0.04%)	⬆️
unittests	80.96% <94.18%> (+0.04%)	⬆️

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.