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
| Rule | master | stable-v5 | bastien-home |
|---|---|---|---|
| Green CI required on the SHA (or a code-identical ancestor) | Syntax Check, Unified CI/CD, Node 22 tests, Homey App Validate | Syntax Check, Node 22 tests, Homey App Validate | Node 22 tests, Homey App Validate |
| Minimum gap between two uploads | 120 min | 60 min | 60 min |
| Successful uploads per 24 h | 1 | 4 | 4 |
| Lock (concurrency group) | athom-publish-master | athom-publish-stable | athom-publish-bastien |
- CI gate. A
[skip ci]data/docs commit on top of a green SHA is accepted when no code file changed (a version-onlypackage.json/package-lock.jsonbump is not code). Cancelled/skipped runs are ignored. Red or pending (afterCI_GATE_WAIT_MS, default 40 min) → no upload, logged, retried at the next slot. Missing CI on the SHA is dispatched once (CI_GATE_DISPATCH_MISSING, afterCI_GATE_DISPATCH_AFTER_MS). - Spacing. Taken from the build snapshot (
data/status/homey-build-status-<app>.json) merged with the ledgerdocs/knowledge/athom-publish-outcomes.jsonl. Counted successes: states test / live / approved. Overrides:ATHOM_MIN_INTERVAL_MIN,ATHOM_MAX_SUCCESS_PER_24H,ATHOM_CI_REQUIRED(comma list). - Busy. No upload while a previous build of the same app is still processing (a build stuck in
waiting_for_filesfor more than 5 min, or not final after 6 h, is ignored). Re-checked right before the upload step. - Unreadable data. Automatic runs hold (fail closed). A manual dispatch may try.
- Manual override.
override_spacing(workflow_dispatch input, mapped toFORCE_PUBLISH) bypasses spacing and the 24 h cap for a manual run only. It never bypasses the CI gate.
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.
| Kind | Examples | Retry | Breaker | Diagnostic |
|---|---|---|---|---|
| transient | socket hang up, ECONNRESET, ETIMEDOUT, 5xx, timeouts, invalid_state | exactly 1, after >= 300 s + 0-60 s jitter, once the previous build is final | not 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 version | tripped for normal runs; only retry 1 of the chain is exempt; tripped for good after the retry fails | after the retry |
| real | AggregateError with a message, processing_failed (without a transient cause), validation errors, unknown | none | tripped | yes |
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
auto-publish-on-push.yml: gate steps in the breaker job (p3036_go), busy re-check beforeid: pub.publish.yml,verified-publish-and-diagnostics.yml:p3036-gatejob (composite action.github/actions/athom-publish-gate).auto-fix-and-publish.yml: the recovery upload moved to its ownpublishjob underathom-publish-master, after ap3036-gatejob. Plain auto-fix runs never take the lock.draft-to-test.yml,draft-to-test-fleet.yml: job-level per-app lock.publish-self-heal.yml:deferredjob runs.github/scripts/athom-deferred-dispatch.js: a held run leaves anathom-deferred-<app>-<run>artifact; the next slot dispatches the app's workflow once withdeferred_retry=true(automatic run, same gate). Artifacts are never deleted by this job.- stable-v5
publish-stable.yml, bastien-homebastien-publish.yml: same gate and lock names.
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.)