fix(zwave_js,matter): tolerate ambiguous credential writes; universal masked read projection (#1251, #1257)

[raman325]

Proposed change

Two distinct variants of the same regression — 4.x permanently disables lock slots on ambiguous/transient credential-write results that 3.x tolerated — unified by one principle, with the correct mechanism differing by whether the write actually reached the lock.

zwave_js (#1251, working-capability variant — e.g. Schlage BE469/BE469ZP)

Separate from the already-fixed zero-slot-capability variant. Here the lock's capabilities are healthy, but the driver's unified User Code CC setCredential verifies a write by reading the code back and comparing it to what was written. Locks that report the user code back masked/withheld return ERROR_UNKNOWN for a write the lock actually accepted (userIdStatus → Enabled). HA surfaces credential_rejected_unknown; LCM mapped it to CodeRejectedError and disabled the slot. Evidence from a reporter's Z-Wave logs: the code lands (userIdStatus[N]: 1) and is removed ~96 ms later when LCM disables+clears it; on 3.2.1 the same codes persist. (Upstream driver bug reported separately; the verify-by-code-equality should be verify-by-status.)

• Treat credential_rejected_unknown as a completed set (the write landed; the sync manager's last-set tracking + read-back reconcile it) instead of a rejection. Definitive rejections (duplicate / occupied / manufacturer-rules / validation) are unchanged.
• _pin_state now maps masked/withheld codes (empty or all-asterisks) to unreadable on the unified path, matching the UC fallback's _uc_slot_state (which now delegates to it). A masked code is no longer mistaken for a readable (wrong) PIN that can never reconcile against the configured one.
• Reverted an interim UC write-routing broadening: with the universal projection + tolerant writes, healthy-capability UC-only locks work on the unified path. The legacy User Code CC fallback is retained only for the zero-slot capability variant.

matter (#1257 — e.g. Aqara U200)

The same "don't permanently disable a transient failure" principle, but the failure is "not reached" rather than "reached but unverifiable," so the fix routes to retry, not completed-set (retry converges once Matter is ready; treating a not-reached write as completed would risk a silent no-code lockout).

• MatterClientException (e.g. InvalidState: Not connected during startup) is independent of HomeAssistantError and was escaping to the generic handler, which suspended the slot. It (and MatterError) are now caught on set/clear → LockDisconnected (retry).
• An unmapped SetCredential status (unknown(N), observed while a lock isn't ready right after startup) routes to retry (LockDisconnected) rather than a permanent disable. Recognized rejections (occupied) still surface as CodeRejectedError.

Not included (deliberately)

A push-as-commit / pending-confirmation model that would also close a narrow, pre-existing (3.x-equivalent) silent-failure window for genuine unsupervised rejections. It interacts with shared calculate_in_sync / coordinator-merge semantics that other providers depend on (Schlage's eventual-consistency convergence relies on the empty-branch last-set trust; no-downgrade conflicts with out-of-band change detection), so it needs its own per-provider-aware design and PR. Tracked as a follow-up.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (which adds functionality)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes [ISSUE] 4.0.2 Code rejected Credential slot for pin_code must be between 1 and 0 #1251, fixes [ISSUE] Matter lock slots disabled after HA restart due to startup credential sync failures #1257
• Full suite passes locally (1243) + prek clean. New tests: _pin_state masked-projection parametrization; zwave credential_rejected_unknown → completed set; matter unknown(N) and MatterClientException → retry on set and clear.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.15%. Comparing base (055773c) to head (486a863).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1258      +/-   ##
==========================================
+ Coverage   97.11%   97.15%   +0.03%     
==========================================
  Files          54       54              
  Lines        6416     6434      +18     
  Branches      461      461              
==========================================
+ Hits         6231     6251      +20     
+ Misses        185      183       -2     

Flag	Coverage Δ
python	97.71% <100.00%> (+0.04%)	⬆️

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

Files with missing lines	Coverage Δ
...onents/lock_code_manager/providers/_zwave_js_uc.py	100.00% <100.00%> (ø)
...m_components/lock_code_manager/providers/matter.py	100.00% <100.00%> (+0.59%)	⬆️
...components/lock_code_manager/providers/zwave_js.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.