Skip to content

docs: elke27 0.6.0 release cut - #146

Merged
mitchmitchell merged 6 commits into
mainfrom
cursor/docs-elke27-0.6.0-release-cut-8f64
Nov 17, 2026
Merged

mitchmitchell merged 6 commits into
mainfrom
cursor/docs-elke27-0.6.0-release-cut-8f64

Conversation

@mitchmitchell

@mitchmitchell mitchmitchell commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Docs-only 0.6.0 release cut. No version bumps, tags, or GitHub release.

Changes

Verification (branch)

uv run python devtools/lint.py          — passed
uv run ruff check --no-fix src test     — passed
uv run ruff format --check src test     — passed
uv run pytest -k "not test_live_e27_"   — 1449 passed, 9 skipped, 33 deselected
Open in Web Open in Cursor 

Note

Low Risk
Documentation-only PR with no runtime or API implementation changes in the diff.

Reviewed by Cursor Bugbot for commit c29f1cb. Bugbot is set up for automated code reviews on this repo. Configure here.

Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T05:32:00.426238Z 0cc4d2f PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
@mitchmitchell

Copy link
Copy Markdown
Owner Author

Claude (hourly) — tip verdict @ f4d6c06ff4b7036a999f2e4238e555a187a95d6c

Please post the D18 verdict for this exact tip.

@cursor review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0cc4d2fd07

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/release-notes/v0.6.0.md Outdated
Comment on lines +82 to +83
that need a fresh snapshot should call `get_snapshot()` after the command
returns or subscribe to status events.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Correct the fresh-snapshot advice after publication timeout

When the publication deadline expires, calling get_snapshot() immediately after the command returns does not ensure fresh status: get_snapshot() only returns self._snapshot (src/elke27_lib/client.py:2527–2529) and neither waits for publication nor refreshes it. An integration following this upgrade advice can therefore consume the stale area or zone state that the publication wait was intended to avoid. Clarify that the snapshot may still be stale after a timeout and that callers requiring confirmed fresh state must wait for publication rather than merely read it again.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in bf37c9b follow-up (latest push):

  1. Publication timeout (P2): Removed the advice that get_snapshot() after a timeout yields fresh state. The release notes now state the snapshot may stay stale until dispatch publishes the status, and point integrators at subscribe() / events() for Elke27Event with EventType.AREA or EventType.ZONE, or a later status read.

  2. Disconnect messages: Split the two Elke27DisconnectedError texts—Connection lost during the command. (reply still pending) vs Connection lost while waiting for snapshot publication. (after reply, before publication)—per client.py _disconnected_from_connection_lost and _fail_all_reply_publication_waiters.

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: Changes needed @ f4d6c06

Docs-only release cut for 0.6.0 (minor, per the D57 ruling). I checked the notes against src/ at this head. The firmware gate (0.0.5.37, required/actual), the hierarchy of every error class in the table, Elke27PanelError.panel_error_code/reason, the route=("area", "set_arm_state") outcome-unknown paths, the WARNING-and-ok on an expired wait budget, and the disconnect message all match the code. Two blockers:

B1: the status-read wait list leaves out zone_get_status. REPLY_PUBLICATION_COMMAND_KEYS (client.py ~494) is area_set_arm_state, area_get_status, zone_set_status, zone_get_status, zone_get_all_zones_status. _command_needs_reply_publication_wait returns True unconditionally for zone_get_status. It is also the follow-up read after an ack-only zone_set_status (client.py ~1665). Both CHANGES ("Status reads (#144)") and v0.6.0.md ("Behavior" and "Area and zone status reads") name only area_get_status and zone_get_all_zones_status. Add zone_get_status to both lists. Also state that the ack-only arm/bypass paths wait on their follow-up reads.

B2: the notes say "raises" for status-read failures, but async_execute returns them. At client.py ~3576, Elke27DisconnectedError and Elke27SnapshotPublicationError from the publication wait are caught and returned as _err(...). That is Result(ok=False, error=...), and nothing is raised from async_execute. CHANGES says link loss or close "raises Elke27DisconnectedError" and that a replace failure "raises Elke27SnapshotPublicationError". v0.6.0.md says waiters "fail with" and the command "returns" the error. An integration that wraps async_execute in try/except would never see these errors. Say plainly that for async_execute they arrive as Result.error with ok=False. They are raised only by the typed helpers that go through _raise_v2_command_error (for example async_arm_area and zone bypass). Fix both files so they say the same thing.

Should-fix items (not blocking; tracked on elke27#50):

  • The release date reads 2026-11-17 in both files. Match it to the actual tag day, since the tag still needs Mitch's OK.
  • README still doesn't name Elke27PanelApplicationFirmwareUnknownError, Elke27NightArmFirmwareTooOldError or Elke27SnapshotPublicationError. This is #142 S1, carried on elke27#50.

There is no code in this diff, so the Bugbot gate doesn't apply. CI was still pending at review time.

…830)

Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision 55 Not approved (offline only) @ f4d6c06

I ran these checks independently at this exact head. The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main. No hardware was used; this is offline only.

Diff scope: docs only. git diff origin/main...HEAD touches just two files: docs/CHANGES.md (+31/−20) and the new docs/release-notes/v0.6.0.md (+95). Nothing changed under src/, test/, pyproject.toml, uv.lock, CI or examples. No code changed, so I ran no mutants.

Version consistency. pyproject.toml has dynamic = ["version"] (uv-dynamic-versioning), and there is no __version__ in src/. The package version comes only from the git tag, and this head builds as 0.5.2.dev6+f4d6c06. CHANGES (0.6.0, 2026-11-17), the release-notes title and the compare/v0.5.1...v0.6.0 link all agree on 0.6.0. I found no stale version strings in README or the other docs. The published version is 0.6.0 only if the v0.6.0 tag goes on the merge commit.

Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:

Gate f4d6c06 7740113
pytest -k "not test_live_e27_" 1449 passed / 9 skipped / 33 deselected 1449 / 9 / 33
basedpyright 0 errors, 0 warnings 0 errors
devtools/lint.py passed passed
ruff check --no-fix (src, test) / format --check clean / 251 files formatted same
ruff repo-wide 6 findings, all in examples/ same 6
test_review_guards.py and private-access ceilings 10 passed 10 passed

The gates pass and match main exactly, which is expected for a docs-only change. The verdict depends only on whether the docs are accurate.

Doc claims I verified against src/ at this head:

  • Every row of the error-class table is correct, and every class is exported.
  • DelayState exists, and so do the async_arm_area(area_id, *, mode: ArmMode, ...) signature, PanelInfo.application_firmware, AreaState.night_arm_supported, delay_state, and the arming/entry_delay properties.
  • An expired wait budget does give ok plus a WARNING.

Blockers (the fix in each case is to make the docs match the code, not the other way round):

  1. zone_get_status is missing from the status-read wait list. REPLY_PUBLICATION_COMMAND_KEYS is area_set_arm_state, area_get_status, zone_set_status, zone_get_status, zone_get_all_zones_status. zone_get_status always waits, and it is also the follow-up read after an ack-only zone_set_status. CHANGES ("Status reads (#144)") and v0.6.0.md ("Behavior" and the bullets under "Area and zone status reads") list only area_get_status and zone_get_all_zones_status. Fix: add zone_get_status to both files.
  2. CHANGES says "raises" for something async_execute returns. Link loss, client close and snapshot-replace failure during the publication wait are caught inside async_execute and returned as Result(ok=False, error=Elke27DisconnectedError | Elke27SnapshotPublicationError). That is the #143 contract, and nothing is raised. CHANGES says each "raises". The release notes are closer ("fail with", "returns") but never say that the error arrives as Result.error. An integration that wraps async_execute in try/except because it read the changelog would never see these failures. Fix: say in both files that for async_execute these arrive as Result.error with ok=False, and that they are raised only by the typed helpers that go through _raise_v2_command_error (async_arm_area, zone bypass).

Should-fix (non-blocking):

  • v0.6.0.md, publication-timeout bullet: the advice to call get_snapshot() after the command returns does not get fresh state. get_snapshot() only returns the current snapshot. This agrees with the existing P2 inline comment. Fix: say the snapshot may still be stale after a timeout, and that callers who need confirmed state should subscribe to status events or re-issue the read.
  • v0.6.0.md quotes the disconnect message "Connection lost while waiting for snapshot publication." That text is used only for waiters failed by the disconnect event. If the link drops while the reply itself is still pending, async_execute returns Elke27DisconnectedError("Connection lost during the command.") (client.py ~1059). Fix: drop the exact quote, or name both messages.
  • The release date says 2026-11-17 in both files. It should match the actual tag day.

Re-review scope: docs only. After a follow-up commit, I'll re-check the diff scope, rerun the gates once, and re-verify the corrected wording against src/.

@mitchmitchell

Copy link
Copy Markdown
Owner Author

Claude (hourly) — tip verdict @ bf37c9b41d80c244e347526a1dd5286ac876e79b

Please post the D18 verdict for this exact tip.

@cursor review

@mitchmitchell

Copy link
Copy Markdown
Owner Author

re-review @ bf37c9b — addresses Architect 5933463830 B1 (zone_get_status and ack-only follow-up reads listed, matching REPLY_PUBLICATION_COMMAND_KEYS) and B2 (async_execute returns Result(ok=False, error=...); only _raise_v2_command_error helpers raise), plus README names the three new errors.

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: Approved (code) @ bf37c9b

Re-review of bf37c9b (docs only). B1 fixed: CHANGES, v0.6.0.md and README now list zone_get_status and the ack-only follow-up reads, matching REPLY_PUBLICATION_COMMAND_KEYS and _command_needs_reply_publication_wait. B2 fixed: all three files say async_execute returns Result(ok=False, error=...) and only the typed helpers raise. README now names the three new errors. One new should-fix is on elke27#50: the public notes name the private _raise_v2_command_error; name the public helpers instead (for example async_arm_area and zone bypass). The release-date should-fix still applies. Bugbot gate n/a (no code). CI was pending at review time.

…ews)

Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
@mitchmitchell

Copy link
Copy Markdown
Owner Author

Claude (hourly) — tip verdict @ 4469e9da8766452a44c4ff049c68eb9238f03c00

Please post the D18 verdict for this exact tip.

@cursor review

@mitchmitchell

Copy link
Copy Markdown
Owner Author

re-review @ 4469e9d — adds Tester 5933494702 should-fixes (no fresh-snapshot claim after publication timeout, per P2 4595731644; both disconnect messages named) and Architect elke27#50 6939690184 (public helpers named instead of the private raise helper; the six named helpers match the six call sites in client.py).

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: Approved (code) @ 4469e9d

Docs-only follow-up checked against src/ at this head: the six named helpers match the six _raise_v2_command_error call sites in client.py, both disconnect messages match client.py (1059 and 2010), subscribe()/events()/EventType.AREA/ZONE exist, and no private helper name is left in README or docs. This closes the elke27#50 item from comment 6939690184 and Tester's 5933494702 should-fixes.

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision 55 Approved (offline only) @ 4469e9d

I checked this head myself, offline only (no hardware). The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main.

Release note: the package version comes from the git tag (dynamic = ["version"], no __version__), and this head builds as 0.5.2.dev8+4469e9d. The v0.6.0 tag must go on the merge commit. I accept 2026-11-17 in CHANGES and v0.6.0.md as the planned tag day, but the date must match the day the tag is actually created.

Scope: docs and README only. git diff origin/main...HEAD changes README.md (+20/−6), docs/CHANGES.md and docs/release-notes/v0.6.0.md (new). Nothing changed in src/, test/, pyproject.toml, uv.lock, CI or examples, so I ran no mutants. Since bf37c9b only the same three docs files changed (+21/−15).

Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:

Gate 4469e9d 7740113
pytest -k "not test_live_e27_" 1449 passed / 9 skipped / 33 deselected 1449 / 9 / 33
basedpyright 0 errors, 0 warnings 0 errors
devtools/lint.py passed passed
ruff check --no-fix (src, test) / format --check clean / 251 files same
ruff repo-wide 6 findings, all in examples/ same 6
test_review_guards.py and private-access ceilings 10 passed 10 passed

Developer's claims, each checked against src/:

  • B1 fixed. zone_get_status is listed in CHANGES, v0.6.0.md and README. The code matches: REPLY_PUBLICATION_COMMAND_KEYS includes it, and _command_needs_reply_publication_wait returns True for it. The new wording on ack-only writes versus confirmed-status writes also matches. When an area_set_arm_state/zone_set_status reply carries confirmed status, that write waits on its own reply. Otherwise the follow-up area_get_status/zone_get_status (itself an async_execute) does the waiting.
  • B2 fixed. async_execute catches Elke27DisconnectedError/Elke27SnapshotPublicationError from the publication wait and returns _err(...), which is Result(ok=False, error=...). All three files now say "returns … does not raise".
  • No fresh-snapshot claim after a timeout. The timeout bullet now says get_snapshot() may still be stale and points to subscribe()/events() or another read. I checked that both work the way the docs say:
    • Elke27Client.subscribe(callback: Callable[[Elke27Event], None], *, kinds=None) -> Callable[[], bool] and events() -> AsyncIterator[Elke27Event] both exist. Elke27Event and EventType (with AREA/ZONE) are exported from elke27_lib.
    • Status events are handled on the loop thread (call_soon_threadsafe(_handle_kernel_event)). Subscriber callbacks run after _replace_snapshot_for_reply_publication. events() consumers resume only after the handler returns. So in both cases get_snapshot() already shows the update when the AREA/ZONE event is delivered.
  • Both disconnect messages are named, and both strings match the source exactly.
    • Reply still pending: _disconnected_from_connection_lost gives "Connection lost during the command." (client.py:1059). This is reached from _await_kernel_command_response on ConnectionLost.
    • Reply in, publication pending: _fail_all_reply_publication_waiters on disconnect gives "Connection lost while waiting for snapshot publication." (client.py:2010).
  • Private helper name replaced. _raise_v2_command_error no longer appears in the changed text. The docs name helpers but show no signatures. async_arm_area, async_disarm_area, async_set_zone_bypass, async_set_output, async_set_barrier and async_refresh_barrier are all public Elke27Client methods (Elke27Client is exported). Each one raises when async_execute returns a failed Result.

README matches the code. It names Elke27PanelApplicationFirmwareUnknownError and Elke27NightArmFirmwareTooOldError, which closes #142 S1, and both are exported from elke27_lib. The PanelInfo.application_firmware and 0.0.5.37/app 1317 gate claims match.

Should-fix (non-blocking, docs only):

  • README ("Status reads … and ack-only arm or bypass follow-up status reads … async_execute returns Result(ok=False, …) when that wait fails") and the matching v0.6.0.md sentence go too far for the ack-only write path. When the follow-up read's publication wait fails, _status_refresh_after_successful_write swallows it. The outer area_set_arm_state/zone_set_status async_execute returns Result(ok=True, status_refresh_ok=False), logs a WARNING and marks the area or zone stale. That is the existing contract, already in CHANGES under the status-refresh entry. Fix: say that a failed follow-up read shows up as status_refresh_ok=False on a successful write Result. ok=False applies only to direct status reads and to writes whose own reply carried confirmed status.

…3568227)

Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
@mitchmitchell

Copy link
Copy Markdown
Owner Author

Claude (hourly) — tip verdict @ 2b45917613f4285faf8df7bd511781b6d75e81b6

Please post the D18 verdict for this exact tip.

@cursor review

@mitchmitchell

Copy link
Copy Markdown
Owner Author

re-review @ 2b45917 — Tester 5933568227 should-fix: failed follow-up read after ack-only arm/bypass is documented as Result(ok=True, status_refresh_ok=False) + WARNING + stale; ok=False kept only for publication-wait failures; typed helpers described per client.py (only ARMED_NIGHT arm raises Elke27CommandOutcomeUnknownError; disarm/bypass/other arm modes return, with status_refresh_ok on CommandResult).

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: Changes needed @ 2b45917

Re-review of 4469e9d..2b45917 (README.md, docs/CHANGES.md, docs/release-notes/v0.6.0.md). Checked against src/elke27_lib/client.py at this head.

What's now correct: an ack-only area_set_arm_state / zone_set_status whose follow-up read fails returns Result(ok=True, status_refresh_ok=False), logs a WARNING and marks the area/zone stale (_status_refresh_after_successful_write). async_disarm_area and async_set_zone_bypass return in that case. Only async_arm_area(ArmMode.ARMED_NIGHT) raises Elke27CommandOutcomeUnknownError.

B1 (new in this commit): the scope of the new "ok=False only when the publication wait fails" wording is wrong for ack-only writes.
README.md (around line 258) says that status reads and ack-only arm or bypass follow-up status reads wait for publication, then says async_execute returns Result(ok=False, error=Elke27DisconnectedError | Elke27SnapshotPublicationError) "only when that publication wait fails". docs/CHANGES.md (Status reads #144 bullet) and the error-class paragraph in v0.6.0.md say the same thing without limits. In the code, an ack-only write never returns ok=False for a failed follow-up publication wait. _refresh_snapshot_from_panel_status calls async_execute("area_get_status" | "zone_get_status"). If that nested call's publication wait fails, it comes back as a failed refresh_result, so the write returns ok=True, status_refresh_ok=False (plus WARNING and stale). The outer _await_reply_snapshot_publication / return _err(publication_failed) only runs when _command_needs_reply_publication_wait is true, which for these two commands means the write reply already carried confirmed status. An integrator who reads these docs would expect Elke27SnapshotPublicationError from an ack-only arm or bypass. They will never get it.
Fix: state the two cases in all three files. (a) Direct status reads (area_get_status, zone_get_status, zone_get_all_zones_status), and arm/bypass writes whose reply includes confirmed status, return ok=False with Elke27DisconnectedError or Elke27SnapshotPublicationError when the publication wait fails. (b) For an ack-only arm or bypass, any failure of the follow-up read, including its publication wait, is reported as ok=True, status_refresh_ok=False.

No other findings. Should-fix items stay on #50.

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision 55 Approved (offline only) @ 2b45917

I checked this head myself, offline only (no hardware). The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main.

Release sequencing: the RC runs at the untagged merge SHA, which builds as a 0.5.2.devN+<sha> version. The package version comes from the git tag (dynamic = ["version"], no __version__). The v0.6.0 tag goes on that same merge commit after RC PASS. The 2026-11-17 date in CHANGES and v0.6.0.md must match the tag day.

Scope: docs and README only. 4469e9d..2b45917 changes only README.md (+8/−4), docs/CHANGES.md (+14/−10) and docs/release-notes/v0.6.0.md (+16/−8). Against main, origin/main...HEAD changes only those three files. Nothing changed in src/, test/, pyproject.toml, uv.lock, CI or examples, so I ran no mutants.

Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:

Gate 2b45917 7740113
pytest -k "not test_live_e27_" 1449 passed / 9 skipped / 33 deselected 1449 / 9 / 33
basedpyright 0 errors, 0 warnings 0 errors
devtools/lint.py passed passed
ruff check --no-fix (src, test) / format --check clean / 251 files same
ruff repo-wide 6 findings, all in examples/ same 6
test_review_guards.py and private-access ceilings 10 passed 10 passed

New status_refresh_ok wording, checked against client.py. It is correct:

  • async_execute line 3584 returns _ok(response_payload, status_refresh_ok=status_refresh_ok). _status_refresh_after_successful_write returns False when the follow-up area_get_status/zone_get_status fails, including a publication-wait failure inside that read. It also logs a WARNING ("Panel accepted %s but follow-up status read failed") and calls _mark_area_stale/_mark_zone_stale. The write's Result stays ok=True. This closes my 4469e9d should-fix.
  • async_disarm_area and async_set_zone_bypass do not raise on status_refresh_ok=False. With return_result=True they return CommandResult(status_refresh_ok=...). CommandResult is exported from elke27_lib.
  • async_arm_area(mode=ArmMode.ARMED_NIGHT) raises Elke27CommandOutcomeUnknownError(("area", "set_arm_state"), ...) when status_refresh_ok is False (client.py ~2888). This is inside the if mode is ArmMode.ARMED_NIGHT branch only.
  • ok=False with Elke27DisconnectedError/Elke27SnapshotPublicationError happens only when the command's own publication wait fails (client.py ~3574–3583). That covers direct status reads and writes whose reply carried confirmed status. It matches the docs.

Is ARMED_NIGHT really the "only" path for Elke27CommandOutcomeUnknownError? I grepped every raise site in src/:

  1. client.py ~2890, async_arm_area: raised when status_refresh_ok is False. ARMED_NIGHT only.
  2. client.py ~2777, _raise_if_night_arm_ignored (#142): the panel acked, but the area is missing from the snapshot after refresh. The only caller is the ARMED_NIGHT branch (~2895). ARMED_NIGHT only.
  3. client.py ~974–1042, _outcome_unknown in _await_kernel_command_response: the frame was confirmed sent, but no reply came (deadline, reply timeout or caller cancel) on any non-read-only route. It comes back as Result(ok=False, error=Elke27CommandOutcomeUnknownError). _raise_v2_command_error re-raises it as-is (it is an Elke27Error) from every typed write helper: arm Away/Stay/Night, disarm, bypass, async_set_output, async_set_barrier. On caller cancel, the CancelledError is chained from it. The async_set_barrier docstring says so explicitly.

So "only ARMED_NIGHT" is true for the status_refresh_ok=False case, which is how the new text scopes it. It is not true for Elke27CommandOutcomeUnknownError overall. The docs as written don't claim the general "only": the no-reply case is already in CHANGES (#35, and the 0.5.x entries at lines ~345/~474), and "other helpers raise when async_execute returns ok=False" covers it. Nothing is wrong enough to block.

Should-fix (non-blocking, docs only):

  • The ARMED_NIGHT trigger is incomplete. CHANGES (line ~30) and v0.6.0.md "Upgrade notes" name only status_refresh_ok=False. Site 2 also raises the same error on ARMED_NIGHT when the refresh succeeded but the area is missing from the snapshot. Fix: add "or the area is missing from the snapshot after the refresh".
  • Arm Away/Stay is missing from the non-raising list. With status_refresh_ok=False, async_arm_area in ARMED_AWAY/ARMED_STAY also returns without raising, the same as disarm and bypass. The three files list only async_disarm_area and async_set_zone_bypass. Fix: name "async_arm_area in Away/Stay" alongside them.
  • The error-table row is labelled "(failed night refresh)". Fix: relabel it "(night refresh failed or missing; or no reply after send on any write)" so the label isn't read as "only".
  • Scope of "ok=False only when the publication wait fails". This is the same issue as the Codex review at this SHA. I count it as an ambiguity rather than a blocker, because all three files also say outright that an ack-only arm or bypass whose follow-up read fails returns Result(ok=True, status_refresh_ok=False). The README also adds "(not when the write succeeded but the follow-up read failed)". Still, "that publication wait" in README, and the unqualified sentence in CHANGES and in the v0.6.0.md error paragraph, could be read as covering the follow-up read's wait. That nested async_execute does fail with ok=False, but _status_refresh_after_successful_write turns it into status_refresh_ok=False on the write's ok=True Result. Fix: split the two cases. ok=False applies to direct status reads and to writes whose reply carried confirmed status. For an ack-only write, every follow-up failure, publication wait included, shows up as ok=True, status_refresh_ok=False.

…33614663, 5933633496)

Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
@mitchmitchell

Copy link
Copy Markdown
Owner Author

Claude (hourly) — tip verdict @ c29f1cb6049ece40e91bda4e3fcbf552659eff19

Please post the D18 verdict for this exact tip.

@cursor review

@mitchmitchell

Copy link
Copy Markdown
Owner Author

re-review @ c29f1cb — Architect 5933614663 B1 (two cases: direct reads and confirmed-status writes return ok=False on publication failure; ack-only follow-up failures, including the nested publication wait, give ok=True/status_refresh_ok=False) in README, CHANGES, v0.6.0.md; Tester 5933633496 should-fixes (ARMED_NIGHT missing-area trigger, Away/Stay return without raising, table label, refresh-failed scope vs no-reply path).

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: Approved (code) @ c29f1cb

B1 from 5933614663 is fixed: README, CHANGES and v0.6.0.md now split (a) direct reads and confirmed-status writes (ok=False on publication failure) from (b) ack-only follow-ups (ok=True, status_refresh_ok=False). This matches client.py. Tester's should-fixes match the code too: the ARMED_NIGHT missing-area raise, Away/Stay returning without raising, and the no-reply path through result.ok. One wording should-fix is on elke27#50; it doesn't block.

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision 55 Approved (offline only) @ c29f1cb

I checked this head myself, offline only (no hardware). The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main.

Release sequencing: the RC runs at the untagged merge SHA, which builds as a 0.5.2.devN+<sha> version. The package version comes from the git tag (dynamic = ["version"], no __version__). The v0.6.0 tag goes on that same merge commit after RC PASS. The 2026-11-17 date in CHANGES and v0.6.0.md must match the tag day.

Scope: docs and README only. 2b45917..c29f1cb changes only README.md (+18/−14), docs/CHANGES.md (+20/−19) and docs/release-notes/v0.6.0.md (+57/−36). origin/main...HEAD changes only those three files. Nothing changed in src/, test/, pyproject.toml, uv.lock, CI or examples, so I ran no mutants.

Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:

Gate c29f1cb 7740113
pytest -k "not test_live_e27_" 1449 passed / 9 skipped / 33 deselected 1449 / 9 / 33
basedpyright 0 errors, 0 warnings 0 errors
devtools/lint.py passed passed
ruff check --no-fix (src, test) / format --check clean / 251 files same
ruff repo-wide 6 findings, all in examples/ same 6
test_review_guards.py and private-access ceilings 10 passed 10 passed

Should-fixes from 5933633496, each checked against client.py:

  1. #142 missing-area trigger: fixed. README, CHANGES and v0.6.0.md "Upgrade notes" now say ARMED_NIGHT also raises Elke27CommandOutcomeUnknownError when the area is missing from the snapshot after refresh. That matches _raise_if_night_arm_ignored (~2774–2780). Its only caller is the ArmMode.ARMED_NIGHT branch of async_arm_area (~2895).
  2. Away/Stay don't raise: fixed and correct. In async_arm_area, the status_refresh_ok is False raise (~2888) and the missing-area check both sit inside if mode is ArmMode.ARMED_NIGHT. Away and Stay fall through to return_result/None. All three files now list Away/Stay with disarm and bypass as not raising.
  3. Table label: fixed. It now reads "(ARMED_NIGHT: failed refresh or area missing after refresh; also no-reply on write helpers)". That covers all three raise sites.
  4. Two-case ok=False split (Codex B1, 5933614663): fixed and correct in all three files.
    • (a) _command_needs_reply_publication_wait is True for direct area_get_status/zone_get_status/zone_get_all_zones_status. For area_set_arm_state/zone_set_status it is True only when _command_reply_includes_confirmed_status. A failure in that wait returns _err(...), which is ok=False with Elke27DisconnectedError/Elke27SnapshotPublicationError (~3574–3583).
    • (b) For ack-only writes, the outer wait is skipped. _status_refresh_after_successful_write runs the nested async_execute("area_get_status" | "zone_get_status") through _refresh_snapshot_from_panel_status. Any non-ok nested Result is turned into status_refresh_ok=False, including a nested publication-wait _err, a transport error, or a hit on the write deadline. It also logs a WARNING and marks the entity stale, and the outer call returns _ok(response_payload, status_refresh_ok=...) (~3584).

No-reply caveat (~974–1042): accurate. _outcome_unknown builds Elke27CommandOutcomeUnknownError(route, ...) only when a route is passed and kernel.was_request_sent(seq) holds.

  • The single-response async_execute path (~3517) passes route=None for READ_ONLY_ROUTES and passes (domain, command) for writes. So it applies to the write helpers (arm, disarm, bypass, async_set_output, async_set_barrier) and not to reads.
  • On deadline or reply timeout it comes back as ok=False. _raise_v2_command_error re-raises it unchanged because it is an Elke27Error, so "write helpers raise via the result.ok check" is correct.

Optional nits (non-blocking):

  • Caller cancellation after a confirmed send raises asyncio.CancelledError chained from Elke27CommandOutcomeUnknownError (~1021–1025, ~1032–1039). It is not returned as ok=False. The new text describes only the ok=False case. That is fine for this release, but a half-sentence would make it complete.
  • In case (b), if the nested follow-up read's own publication wait times out without failing, the nested Result is ok=True. The write then reports status_refresh_ok=True even though get_snapshot() may still lag. That is the case (a) timeout rule applied to the nested read. The (a) timeout bullet ("may still show stale state … use subscribe()/events()") could say it applies to ack-only follow-up reads too.

@mitchmitchell mitchmitchell left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs-only release cut; checked the error hierarchy table and the new exports against errors.py / __init__.py at this head and they match.

  • The status-publication (a)/(b) text now lives almost verbatim in README, CHANGES and the release notes. Can the README keep a two-line summary and link to docs/release-notes/v0.6.0.md? Three copies will drift the next time this behavior changes.

No blocking findings.

Verdict: APPROVED @ c29f1cb
joostlek-style review via Claude


Generated by Claude Code

Comment thread docs/CHANGES.md
`reason`, and a warning log) when the panel answers with a non-zero
`error_code`, including single and paged responses. Helpers that already
mapped panel errors via `_raise_v2_command_error` are unchanged.
mapped panel errors; public typed command helpers are unchanged.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence reads broken after the semicolon, and it rewrites a 0.5.0-era entry. Maybe just:

Suggested change
mapped panel errors; public typed command helpers are unchanged.
mapped panel errors (the public typed command helpers) are unchanged.

Generated by Claude Code

@mitchmitchell

Copy link
Copy Markdown
Owner Author

@cursor review

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit c29f1cb. Configure here.

@mitchmitchell
mitchmitchell merged commit 26eb370 into main Nov 17, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants