Universal Tuya docsHomeSupported devicesRequest a deviceFAQChangelogArchitectureKnowledge baseCreditsSourcesContributing

P3036: Athom publish policy (green CI, spacing, one retry, bisect exit)

25/10/2026 (Paris, UTC+1). Applies to master (com.dlnraja.tuya.zigbee), stable-v5 (.stable) and bastien-home (.bastien). Scheduled workflows run from master only.

Why

P3034 closed with 9.0.1599 (#3682): the same payload that had been refused went to draft and then to Test once CI was green and the upload window was quiet. The refusals line up with red CI, uploads sent too close together and Athom-side socket hang up, not with the app content. That is a strong presumption, not a proof. This policy turns those findings into rules that every upload path follows.

Rules

Rulemasterstable-v5bastien-home
Green CI required on the SHA (or a code-identical ancestor)Syntax Check, Unified CI/CD, Node 22 tests, Homey App ValidateSyntax Check, Node 22 tests, Homey App ValidateNode 22 tests, Homey App Validate
Minimum gap between two uploads120 min60 min60 min
Successful uploads per 24 h144
Lock (concurrency group)athom-publish-masterathom-publish-stableathom-publish-bastien

Error classification (one module for every path)

classify() in .github/scripts/athom-publish-policy.js; athom-retry-policy.js and transient-publish-retry.js delegate to it.

KindExamplesRetryBreakerDiagnostic
transientsocket hang up, ECONNRESET, ETIMEDOUT, 5xx, timeouts, invalid_stateexactly 1, after >= 300 s + 0-60 s jitter, once the previous build is finalnot tripped; the retry is exempt (fixes run 40194918949)no
bare AggregateError (P3341)stateMeta exactly AggregateError (empty message)exactly 1 identical retry, P3311 first backoff, only for an existing final failed build of that versiontripped for normal runs; only retry 1 of the chain is exempt; tripped for good after the retry failsafter the retry
realAggregateError with a message, processing_failed (without a transient cause), validation errors, unknownnonetrippedyes

A bare processing_failed row with no reason at all keeps the P3025 rule in athom-classify-failure.js (wait log first, then empty error -> transient): Athom history shows those are mostly hang-ups.

The in-run fallbacks (homey-app-publish action, homey-publish action, Auto-Fix publish job, publish-stable and bastien-publish loops) call athom-publish-policy.js fallback and record ATHOM_RETRY_USED=1, so a run can never retry twice.

Where it is wired

Bisect exit

docs/knowledge/athom-bisect-state.json status=done → bisect-hold.js allows everything: no forced drafts, no bisect_trial. Normal flow: draft → Test automatically when processing is OK. Live is never automatic. If rejections come back, rerun the bisect: set status=running (drafts only + bisect_trial are re-armed).

Env flags

CI_GATE_SHA, CI_GATE_BRANCH, CI_GATE_WAIT_MS, CI_GATE_POLL_MS, CI_GATE_DISPATCH_MISSING, CI_GATE_DISPATCH_AFTER_MS, CI_GATE_SKIP (manual only, not wired in any workflow), EVENT_NAME, TRANSIENT_RETRY, DEFERRED_RETRY, FORCE_PUBLISH, ATHOM_MIN_INTERVAL_MIN, ATHOM_MAX_SUCCESS_PER_24H, ATHOM_CI_REQUIRED, ATHOM_RETRY_USED, ATHOM_REACH_TEST, DEFERRED_DRY_RUN, HOMEY_ZIGBEE_TOPUP_MAX_TOTAL, HOMEY_ZIGBEE_TOPUP_MAX_DRIVER, HOMEY_ZIGBEE_TOPUP_ALLOW_UNMEASURED.

TS0601 couples dropped by the compaction (lead L-P3037-01)

Measurements, root cause and the measured Athom ceiling: ATHOM_LIMITS.md, section "P3036 measured combo ceiling and TS0601 top-up". In short: scripts/maintenance/ts0601-topup.cjs runs after the compaction and only adds missing (manufacturer, TS0601) groups up to HOMEY_ZIGBEE_TOPUP_MAX_TOTAL (20000 = highest combo count Athom accepted from us) and HOMEY_ZIGBEE_TOPUP_MAX_DRIVER (2000). On master it brings back 540 groups (15 498 -> 19 999 combos); 2 162 stay out because the per-driver cartesian product makes them cost ~64k combos in their current drivers. Getting all of them in needs a TS0601-only carrier driver or real probe uploads above 20k: both are owner decisions.

Tests: test/critical/p3036-athom-publish-policy.test.js, test/critical/p3036-ts0601-topup.test.js.

P3057-2 promote guard (26/10/2026)

The autonomous Bastien promote (tools/ci/bastien-promote-upstream.js, P2607) now runs tools/ci/promote-hold-guard.js after the test/compose/budget guards, for master and for stable-v5. While the target has a hold window in config/promote-publish-hold.json or a pending send (target app.json version above the last accepted test/live/approved version in the outcomes ledger or the CI build snapshot; unreadable = held), only test/, .github/, tools/ci/, scripts/ci/, docs/, root *.md and the dataSafetyAllow list are promoted. Drivers, sacred pins, app.json and other lib/ files are restored (reason publish_hold_active) and stay on Bastien until the accept is recorded. Test: test/critical/p3057-2-promote-hold-guard.test.js.

P3341 (16/11/2026, owner go 03:03 Paris): one retry for a bare AggregateError

A bare Athom AggregateError (stateMeta exactly "AggregateError", empty message: the Node net multi-address connect failure) gets exactly ONE identical retry: bumped version, P3311 first backoff (>= 300 s + jitter), only when Athom already holds a final processing_failed build for that version (no duplicate). It keeps class real: push runs stay blocked by the breaker, only retry 1 of the chain is exempt, and a second failure trips the breaker and notifies as before. AggregateError with a message and every other real error get no retry. Why: docs/knowledge/ATHOM_AGGREGATEERROR_P3340.md (identical content flips Test <-> AggregateError; the bare text is Node's connect failure). Code: athom-publish-policy.js (BARE_AGGREGATE_KIND, isBareAggregate, RETRY.maxBareAggregateRetries = 1), athom-retry-policy.js (stable/bastien in-run loops), transient-publish-retry.js (master chain). Test: test/critical/p3341-bare-aggregate-retry.test.js.

P3355 (17/11/2026): retry chain counted per error class

Run 44004265730 was transport retry 1/2 after a socket hang up (#3709); its build #3710 failed with a bare AggregateError and was refused as "single identical retry already used". The chain input transient_retry now carries <total>:t<transport>a<bare> (for example 2:t1a1; parseInt still reads the total). Transport kinds keep up to 2 retries (3 attempts), a bare AggregateError exactly 1 identical retry, and a chain never exceeds 3 retries. A legacy plain number is read the old, stricter way. The breaker exemption uses the same per-class counts. Backoff, idle wait and the same-version / orphan guards are unchanged.

P3357: at most 3 uploads per chain

User rule (2026-11-15): a publish chain makes at most 3 uploads (1 initial + 2 retries), whatever the error mix, then stops and notifies. RETRY.maxChainUploads = 3, RETRY.maxChainRetries = 2. A bare AggregateError still gets at most its one identical retry inside those 3; transport retries fill the rest. The breaker exemption refuses any chain value above 2 retries. (P3355 allowed 3 retries = 4 uploads.)

← Knowledge base index · source