common_config.h

Go to the documentation of this file.

#ifndef RTE_EXAMPLE_COMMON_CONFIG_H
#define RTE_EXAMPLE_COMMON_CONFIG_H
 
#include <stdio.h>
 
#include "rte/utils/safestate/rte_safestate.h"
#include "rte/oal/timer/rte_timer.h"
#include "rte/oal/log/rte_log.h" /* RTE_LOG_WRITE_EVENT[_F] below */

#define RTE_EXAMPLE_LOG(...)                                             \
    do                                                                       \
    {                                                                        \
        rte_timestamp_ms_t rte_example_log_ts_ = 0U;                    \
        (void)rte_timer_now(&rte_example_log_ts_);                      \
        printf("[%10llu] ", (unsigned long long)rte_example_log_ts_);    \
        printf(__VA_ARGS__);                                                 \
        (void)fflush(stdout);                                                \
    } while (0)

#define RTE_LOG_WRITE_EVENT(level, site, cycle, source, dest, type, info, extra) \
    rte_log_write_event((level), (site), (cycle), (source), (dest), (type), (info), (extra))
 
#define RTE_LOG_WRITE_EVENT_F(level, site, cycle, source, dest, type, info_fmt, ...) \
    do                                                                                 \
    {                                                                                 \
        char rte_lwe_info_[RTE_LOG_EVENT_LINE_MAX_LEN];                              \
        (void)snprintf(rte_lwe_info_, sizeof(rte_lwe_info_), (info_fmt), __VA_ARGS__); \
        rte_log_write_event((level), (site), (cycle), (source), (dest), (type),       \
                             rte_lwe_info_, NULL);                                    \
    } while (0)
 
/* Shared by every role (A, B, C) so port numbers and cycle counts never
 * drift apart between the processes that must agree on them - in a real
 * multi-machine deployment these would come from a deployment config
 * file, not compile-time constants; hardcoded here because this is a
 * single-host demo (see README's honest limitations). */
 
/* Per-site port bases. Both West and East run their own full A/B/C group
 * (hot standby: see README/site_config.h) on the SAME host in this demo,
 * so each site needs its own set of ports to avoid colliding with the
 * other site's listeners - in a real multi-machine deployment each site
 * would run on its own host and could reuse the same port numbers
 * (pointing rte_netlink's CONNECT side at a real remote host is the
 * intended path from this single-host demo to that, same as noted for
 * the single-site A/B/C group before West/East existed). See
 * site_config.h for the per-site port lookup helpers built from these. */
/* Gap between the two bases must clear BOTH: (a) the full per-site port
 * range below (currently 16 ports: offsets 0..C_FOR_CTC_PORT_OFFSET, one
 * block per {peer, kind, instance} relay + sim-facing link - grows with
 * RTE_EXAMPLE_MAX_TRAINS), and (b) the two fixed, site-INDEPENDENT
 * negotiation ports below (15021/15022 - deliberately not derived from
 * either base, see their own doc on why). Only matters for this project's
 * local/smoke-test topology, where every site runs as a plain process on
 * one shared host (127.0.0.1) - two sites' ranges only need to stay apart
 * there; in the real docker-compose topology each site is a separate
 * host/network-namespace, so identical port *numbers* across sites never
 * collide regardless of this gap. Found the hard way this session: the
 * per-instance relay channel expansion grew the per-site range from ~7 to
 * 16 ports without widening this gap to match, so WEST's own range
 * (15001-15016) silently overran EAST's old base (15011) - and EAST's own
 * range (15011-15026) in turn swallowed the negotiation ports (15021/22)
 * too. Two UDP sockets in two different processes both bound (SO_REUSEADDR)
 * to the same port on localhost is not a bind() failure - it's silent,
 * kernel-dependent datagram misdelivery, which surfaced as an
 * indistinguishable-from-deadlock hang (one side's HELLO handshake waiting
 * forever on a socket the OS was routing to a different process' socket
 * instead) only when WEST+EAST ran together, not in either site alone.
 * Generous headroom (100, not just "enough for today") is deliberate so
 * the next MAX_TRAINS/relay-kind increase doesn't reintroduce this exact
 * bug the same way. */
#define RTE_EXAMPLE_WEST_PORT_BASE 15001U
#define RTE_EXAMPLE_EAST_PORT_BASE 15101U
 
/* Fixed bound on concurrently-tracked train sessions per site (RBC
 * Train/IL/CTC scenario, ADR-029) - a compile-time array size everywhere a
 * session table exists (monitor_c_types.h, ab_gp_channel_types.h), never a
 * dynamic list (CLAUDE.md: no malloc/free/realloc). Exactly matches the
 * number of live Train/IL container pairs this docker-compose topology
 * runs (train-west+il-west, train-east+il-east) - see docker-compose.yml. */
#define RTE_EXAMPLE_MAX_TRAINS 2U
 
/* Fixed bound for AB/db's own RUNTIME route table (ab_gp_db.h,
 * ab_gp_db_route_t routes[RTE_EXAMPLE_MAX_ROUTES]) - same
 * "compile-time array size, never a dynamic list" convention as
 * RTE_EXAMPLE_MAX_TRAINS above. This is NOT the static site
 * TOPOLOGY's own size (safeAPIRBC2oo2GA's generated ab_siteGA.c's ab_site_ga_track_layout[] is
 * a plain extern array, sized by its own initializer, uncapped by any
 * constant here) - it only needs to hold routes CURRENTLY granted/
 * tracked at once, bounded by RTE_EXAMPLE_MAX_TRAINS *
 * _MAX_ROUTES_PER_TRAIN (2*4=8 today) regardless of how large the static
 * layout itself is. RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN bounds how many
 * of those a single train can have allocated to it at once (an MA
 * spanning more than one route section). */
#define RTE_EXAMPLE_MAX_ROUTES 8U
/* Guarded, not a plain #define: ga_interface.h (GP's own exported facade
 * for safeAPIRBC2oo2GA, now a separate shared-library project) ALSO
 * defines this same constant, guarded the identical way - both this file
 * and a GA-facing translation unit that includes ga_interface.h first
 * need to agree, whichever is included first wins, no redefinition
 * warning either way. Keep both copies' VALUE in sync if this ever
 * changes. */
#ifndef RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN
#define RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN 4U
#endif
 
/* RTE_EXAMPLE_MAX_BALISES_PER_ROUTE/_MAX_SEGMENTS_PER_ROUTE/
 * _MAX_SWITCHES_PER_ROUTE used to live here, but were moved into
 * safeAPIRBC2oo2SA's own ab_site.h when that module was extracted into
 * its own project - nothing outside ab_site.h ever referenced them
 * (confirmed at extraction time), genuinely that module's own concern. */
 
#define RTE_EXAMPLE_AB_PORT_OFFSET              0U  /* A listens, B connects: peer/checkpoint link */
#define RTE_EXAMPLE_AB_CROSSCOMPARE_PORT_OFFSET 16U /* A listens, B connects: dedicated cross-compare link */
/* C listens, A/B connect: dedicated relay links, one per {peer, kind,
 * instance} (this session's own addition - see site_config.h's own
 * rte_example_relay_kind_t doc). Train/IL each need
 * RTE_EXAMPLE_MAX_TRAINS ports per peer (site_config_c_port_for_a()/
 * _for_b() add an instance index on top, 0..RTE_EXAMPLE_MAX_TRAINS-1,
 * same "base + index" shape as C_FOR_TRAIN_PORT_OFFSET/C_FOR_IL_PORT_OFFSET
 * below) - CTC stays a single port per peer (only ever index 0), since
 * there is only ever one CTC instance. Kept as two separate contiguous
 * blocks (A's own Train+IL+CTC ports, then B's own) rather than
 * interleaved, so each side's own ports stay easy to eyeball in a port
 * scan. */
#define RTE_EXAMPLE_C_FOR_A_TRAIN_PORT_OFFSET 1U
#define RTE_EXAMPLE_C_FOR_A_IL_PORT_OFFSET \
    (RTE_EXAMPLE_C_FOR_A_TRAIN_PORT_OFFSET + 1U)
#define RTE_EXAMPLE_C_FOR_A_CTC_PORT_OFFSET (RTE_EXAMPLE_C_FOR_A_IL_PORT_OFFSET + 1U)
/* ADR-038: A's general util side channel to C (rbc_util_frame_t). */
#define RTE_EXAMPLE_C_FOR_A_UTIL_PORT_OFFSET (RTE_EXAMPLE_C_FOR_A_CTC_PORT_OFFSET + 1U)
#define RTE_EXAMPLE_C_FOR_B_TRAIN_PORT_OFFSET (RTE_EXAMPLE_C_FOR_A_UTIL_PORT_OFFSET + 1U)
#define RTE_EXAMPLE_C_FOR_B_IL_PORT_OFFSET \
    (RTE_EXAMPLE_C_FOR_B_TRAIN_PORT_OFFSET + 1U)
#define RTE_EXAMPLE_C_FOR_B_CTC_PORT_OFFSET (RTE_EXAMPLE_C_FOR_B_IL_PORT_OFFSET + 1U)
#define RTE_EXAMPLE_C_FOR_B_UTIL_PORT_OFFSET (RTE_EXAMPLE_C_FOR_B_CTC_PORT_OFFSET + 1U)
/* C listens, one Train sim instance connects: P0/M136 down^H^H up, M24/M15/M3
 * down - rte_netlink's RTE_NETLINK_ROLE_LISTEN accepts exactly one peer
 * per bound port (rte_netlink.h), so RTE_EXAMPLE_MAX_TRAINS concurrent
 * trains each need their OWN port - this is a BASE offset, not a single
 * port; site_config_c_port_for_train(site, train_index) adds train_index
 * (0..RTE_EXAMPLE_MAX_TRAINS-1) on top. Same for IL below. Right after
 * the A/B relay ports above. */
#define RTE_EXAMPLE_C_FOR_TRAIN_PORT_OFFSET (RTE_EXAMPLE_C_FOR_B_UTIL_PORT_OFFSET + 1U)
/* One port per IL instance (base + il_index), same reasoning as Train
 * above - IL instance N sets routes for train instance N's session (see
 * site_config_c_port_for_il()). Reserves offsets
 * [C_FOR_TRAIN_PORT_OFFSET .. +RTE_EXAMPLE_MAX_TRAINS-1] for Train, so
 * this starts right after that block. */
#define RTE_EXAMPLE_C_FOR_IL_PORT_OFFSET (RTE_EXAMPLE_C_FOR_TRAIN_PORT_OFFSET + 1U)
/* C listens, the single CTC sim connects: one-way status push
 * notifications only (train connected/MA granted/MA extended) - see
 * rbc_wire_types.h. Right after IL's own block. */
#define RTE_EXAMPLE_C_FOR_CTC_PORT_OFFSET (RTE_EXAMPLE_C_FOR_IL_PORT_OFFSET + 1U)
/* ADR-038: the C-side status/broker service LISTENs one port per local
 * gateway service (train/il/ctc) so each can CONNECT and publish its own
 * status frames - "one link per client", same posture as every other
 * role-C link. Right after the sim-facing block. */
#define RTE_EXAMPLE_C_FOR_BROKER_TRAIN_PORT_OFFSET (RTE_EXAMPLE_C_FOR_CTC_PORT_OFFSET + 1U)
#define RTE_EXAMPLE_C_FOR_BROKER_IL_PORT_OFFSET (RTE_EXAMPLE_C_FOR_BROKER_TRAIN_PORT_OFFSET + 1U)
#define RTE_EXAMPLE_C_FOR_BROKER_CTC_PORT_OFFSET (RTE_EXAMPLE_C_FOR_BROKER_IL_PORT_OFFSET + 1U)
 
/* Inter-site negotiation links (replaces the old standalone SITE<->SITE
 * link - see ab_gp_channel.c's own "negotiate" step, folded directly into
 * A and B): A-WEST<->A-EAST and B-WEST<->B-EAST are two SEPARATE links,
 * one owned by each channel, so site-level negotiation is never a single
 * point of failure the way one shared SITE process/link used to be. Each
 * is a single fixed port (not a per-site offset): WEST always LISTENs,
 * EAST always CONNECTs (fixed technical role, unrelated to which site
 * ends up ONLINE - same convention the old SITE link used), and exactly
 * one such link exists per channel regardless of site. */
#define RTE_EXAMPLE_A_NEGOTIATION_PORT 15021U
#define RTE_EXAMPLE_B_NEGOTIATION_PORT 15022U
 
#define RTE_EXAMPLE_LOCALHOST      "127.0.0.1"
 
/* ---------------------------------------------------------------------
 * Container-friendly host resolution
 * ---------------------------------------------------------------------
 * Every CONNECT-role endpoint in this example used to hardcode
 * RTE_EXAMPLE_LOCALHOST - fine when every role ran as a plain OS
 * process on one host, not once A, B, and C become genuinely separate
 * containers/machines. Each env var below overrides ONE specific
 * CONNECT-role link's target host; unset (the default for
 * etc/run_all.sh/.claude/skills/run-safeAPIRBC2oo2/smoke.sh, both still
 * fully localhost-based) falls back to RTE_EXAMPLE_LOCALHOST, so the
 * existing local/manual launch path needs zero changes. Docker Compose
 * sets these per-service to the peer container's own service-DNS name
 * (see docker-compose.yml). Read via site_config_host() below. */
#define RTE_EXAMPLE_C_HOST_ENV        "RTE_EXAMPLE_C_HOST"        /* A/B (any site) -> this site's C */
#define RTE_EXAMPLE_A_HOST_ENV        "RTE_EXAMPLE_A_HOST"        /* B (any site) -> this site's A (peer link) */
#define RTE_EXAMPLE_REMOTE_A_HOST_ENV "RTE_EXAMPLE_REMOTE_A_HOST" /* A-EAST -> A-WEST (negotiation) */
#define RTE_EXAMPLE_REMOTE_B_HOST_ENV "RTE_EXAMPLE_REMOTE_B_HOST" /* B-EAST -> B-WEST (negotiation) */
 
/* ADR-029 addendum #2 (attempted, REVERTED): live GitHub Actions CI
 * testing (shared 2-vCPU runner, 11 containers) found the inter-site
 * negotiation link repeatedly faulting ("no ack within
 * RTE_EXAMPLE_NEGOTIATION_WATCHDOG_TIMEOUT_MS") well into steady-state
 * operation, alongside the separate AB_CHECKPOINT_MAX_DELAY_MS misses
 * that prompted a matching RTE_EXAMPLE_AB_CYCLE_PERIOD_MS widening
 * attempt (see that constant's own doc) - both pointed at the same
 * underlying cause (severe CPU/I/O contention on a real CI runner, well
 * beyond what a local developer machine exhibits). Raising this
 * constant 3000ms -> 5000ms alongside that attempt was tried, but found
 * live to REGRESS local stability (this project's own previously rock-
 * solid 11/11 local Robot suite dropped to 6/11 on the SAME machine,
 * SAME code, with only these timing constants changed - confirmed by
 * reverting just the constants and re-running, 11/11 again) - kept at
 * 3000ms. The CI-side instability this was meant to fix remains open;
 * see RTE_EXAMPLE_AB_CYCLE_PERIOD_MS's own doc for the working
 * theory on why widening made things worse instead of better, and for
 * why the fix belongs at the CI-environment layer, not here. */
#define RTE_EXAMPLE_LINK_TIMEOUT_MS    300U
#define RTE_EXAMPLE_NEG_ACK_TIMEOUT_MS 50U
 
/* ISS-020: open gate of the UTIL relay link (ab-relay-util, ab_gp_util_link_gate.h). The link carries only non-safety
 * traffic (status publish, JRU/diagnostic log forwarding, ADR-001 section 4), its open runs on the cycle thread and
 * blocks until the status service answers the handshake or the timeout runs out. While the status service is absent,
 * the cycle thread may spend at most RTE_EXAMPLE_UTIL_OPEN_ATTEMPT_TIMEOUT_MS on one attempt per
 * RTE_EXAMPLE_UTIL_REOPEN_BACKOFF_MS (0.4 % of the cycle budget), instead of RTE_EXAMPLE_LINK_TIMEOUT_MS per INFO log
 * event and the channel's 1000 ms connect timeout per cycle (measured 1298 ms per cycle on the read path).
 * - Back-off 5000 ms = RTE_EXAMPLE_STATUS_PERIOD_MS: a status service that comes up later is reached at most one
 *   status period later than without the gate; nothing is queued for it before that (best-effort, as before).
 * - Attempt 20 ms: well under the 50 ms the inter-site link's per-cycle reconnect attempt may block the cyclic
 *   executive (AB_GP_NEG_RECONNECT_ATTEMPT_MS) and under RTE_EXAMPLE_NEG_ACK_TIMEOUT_MS, so the negotiation link
 *   serviced between cycles is not starved; a loopback or LAN peer that services its socket answers HELLO within a
 *   few ms. Applies to attempts before the first success only; once open, sends use RTE_EXAMPLE_LINK_TIMEOUT_MS as
 *   before (a send on an open UDP link does not block). */
#define RTE_EXAMPLE_UTIL_REOPEN_BACKOFF_MS      5000U
#define RTE_EXAMPLE_UTIL_OPEN_ATTEMPT_TIMEOUT_MS 20U
 
/* Subset-026 T_NVCONTACT: maximum silence from a train with an active
 * ERTMS session (ab_gp_proc_session_check_timeout(), called once per cycle
 * from ab_gp_ertms_engine_step() with the real elapsed_ms) before the
 * session is torn down. Found live disabled: engine_step() passed a
 * literal 0U here instead of a real threshold, and check_timeout()'s own
 * `timeout_limit_ms > 0U` guard (a deliberate "0 = supervision off" opt-out
 * for that function's other, non-cyclic callers - see its own header doc)
 * silently no-oped every single call, so T_NVCONTACT supervision never
 * actually fired for any train, ever. This default is a placeholder, not
 * a value taken from a real National Values message: this codebase does
 * not yet store a per-train Packet 3 (National Values) T_NVCONTACT once
 * received (ab_gp_proc_dispatch.c's own Msg 24 encode path has has_national_values,
 * but nothing decodes one back in and stores it per train) - wire that up
 * and use it here in place of this constant when that lands. */
#define RTE_EXAMPLE_ERTMS_CONTACT_TIMEOUT_MS 20000U
 
/* ADR-038 status indication: every unit publishes its status (and logs
 * its own self line) at startup and every _PERIOD_MS; the C-side
 * aggregator renders a source "down" once its last frame is older than
 * _STALE_MS (3 missed periods). Non-safety - a monitoring path. */
#define RTE_EXAMPLE_STATUS_PERIOD_MS 5000U
#define RTE_EXAMPLE_STATUS_STALE_MS  15000U
/* ADR-029 section 2.6 addendum: raised 5000ms -> 60000ms after a severe
 * crash-loop found live in fault_injection/ testing once
 * ab_gp_channel_safestate_handler (ab_gp_channel.c) started correctly
 * re-routing a checkpoint-connectivity timeout through this channel's own
 * REBOOT recovery path instead of a silent permanent halt (see that
 * handler's own doc). main.c's own startup sequence - ab_gp_channel_open_link()'s
 * peer link, ab_gp_channel_negotiate_setup()'s negotiation link, and
 * ab_gp_channel_relay_tasks_setup()'s C relay links - all share this ONE
 * bounded "give up and exit the process" window (main.c calls
 * rte_appmanager_run() exactly once and relies entirely on
 * docker-compose's `restart: unless-stopped` for any retry - there is no
 * in-process retry loop around init itself, unlike every ONGOING
 * reconnect in this codebase, which retries forever). During a real
 * network-partition fault-injection test (tests/robot/fault_injection/),
 * the partition can legitimately still be in effect for
 * RTE_EXAMPLE_EXTENDED_PARTITION_SECONDS-class durations (tens of
 * seconds) - a rebooted process whose own re-init hits the SAME still-
 * ongoing partition within the old 5s window would immediately fail
 * init and exit, docker would immediately respawn a brand-new container
 * that ALSO immediately re-hits the same still-ongoing partition, and so
 * on for the whole partition duration - observed live as 30+ container
 * restarts within a few minutes (RestartCount), the exact crash-loop
 * MAX_ACCEPTABLE_RESTARTS_PER_FAULT (tests/robot) exists to catch. Raised
 * comfortably past the worst-case fault-injection partition length so a
 * reboot triggered mid-partition gets a REAL chance to reconnect once the
 * partition actually lifts, rather than repeatedly racing (and losing)
 * against a fault that has not yet resolved - this is a demo/first-pass
 * choice (a real product would give init its own retry-forever loop
 * instead of a single bounded window backed by a container restart), not
 * a claim that 60s is itself some principled ceiling. */
#define RTE_EXAMPLE_CONNECT_TIMEOUT_MS 10000U
 
/* Bounded wait per attempt for a *background* link reconnect loop (peer or
 * C link dying mid-run and being re-established without giving up - see
 * ab_gp_channel.c/monitor_c.c). Deliberately shorter than
 * RTE_EXAMPLE_CONNECT_TIMEOUT_MS (used for the one-time initial
 * open, where giving up quickly would be wrong): a background reconnect
 * loop retries forever anyway, so each individual attempt should be short
 * enough that the loop also re-checks its own stop-requested flag
 * promptly during shutdown. */
#define RTE_EXAMPLE_RECONNECT_ATTEMPT_TIMEOUT_MS 1000U
 
/* ADR-027 Phase 2: consecutive RTE_STATUS_TIMEOUT results (each already
 * bounded to RTE_EXAMPLE_LINK_TIMEOUT_MS) a raw, unframed netlink
 * link's own rx task tolerates before treating the link as dead and
 * closing it for reconnect - the peer link (ab_gp_channel_io.c) and C's two
 * links (monitor_c_io.c). Under UDP there is no transport-level "peer
 * disconnected" signal for these links (unlike the negotiation link,
 * which has rte_dual_channel's own ACK-timeout-based liveness) - a
 * receive() call that only ever returns TIMEOUT, forever, is the sole
 * signal available that the peer's process has restarted, and this many
 * consecutive occurrences (~RTE_EXAMPLE_LINK_TIMEOUT_MS * this value)
 * is treated as "gone", not "quiet this cycle".
 *
 * ADR-029: raised from 2 to 4 (6s -> 12s) - same root cause as
 * RTE_EXAMPLE_AB_CYCLE_SKEW_TOLERANCE/_AB_DUAL_TRANSFER_TIMEOUT_MS's
 * own doc: the C<->A/B link (this same constant also governs
 * monitor_c_io.c's rx_a/rx_b tasks) now only carries traffic when there
 * is real train/IL activity to relay, which arrives roughly once per
 * sims/train_sim.py's own RTE_EXAMPLE_SIM_PERIOD_SECONDS (2000ms
 * default) rather than every ~600ms cycle - and specifically, A/B's own
 * REPLY traffic back to C is additionally gated on cross-compare having
 * AGREED at least once, which can itself take several train-report
 * cycles to first settle after a fresh start/reconnect. The old 6s
 * window was found live to spuriously fire during that ordinary startup
 * ramp-up, closing/reopening a perfectly healthy link mid-flight - and
 * because this link carries one-time, non-repeating events (ROUTE_ADD,
 * M146), unlike M136's own self-healing-next-report tolerance, a
 * datagram lost to that exact reconnect window is gone for good and
 * causes a genuine, spurious cross-compare DISAGREE (found live: an
 * IL's very first commanded ADD_ROUTE landed on A mid-reconnect and
 * never arrived, while B received it fine, diverging the two channels'
 * otherwise-identical session tables). Kept comfortably under
 * RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS (20s) - this stays the fast,
 * lightweight "just reopen the socket" path; that stays the slow,
 * drastic escalation. */
#define RTE_EXAMPLE_LINK_STALE_TIMEOUT_COUNT 4U
 
/* ADR-027 Phase 2: bounded grace period after the peer link reconnects
 * before the built-in checkpoint is re-armed regardless of whether any
 * data has arrived yet - see checkpoint_pending_reenable's own doc
 * (ab_gp_channel_types.h) for why a pure "wait for incoming data" gate can
 * deadlock (checkpoint's own send is what the peer needs to receive to
 * clear ITS OWN pending flag) and why this fallback exists.
 *
 * ADR-029: raised 600ms -> 15000ms after a real, reproducible permanent
 * hang found in full 11-container Docker testing - live gdb attach to a
 * stuck A/B process (main thread pinned at 100% CPU, wchan=0, spinning in
 * rte_safestate_enter() via rte_channel_checkpoint()) showed the built-in
 * checkpoint entering an UNRECOVERABLE SAFE-state halt (by design,
 * REQ-CHECKPOINT-003 - this is not itself a bug) shortly after a peer-link
 * stale/reconnect event. Root cause: this socket reconnecting proves only
 * that the LOCAL send/receive path is usable again, not that the PEER's
 * own reconnect (bounded by the independent
 * RTE_EXAMPLE_LINK_STALE_TIMEOUT_COUNT * RTE_EXAMPLE_LINK_TIMEOUT_MS
 * ~= 12s window) has also completed - under real Docker load the two
 * sides' reconnects are not synchronized, so the old 600ms was routinely
 * far shorter than the peer's own recovery time, force-re-arming the
 * checkpoint (and its intentionally tight 450ms
 * RTE_EXAMPLE_AB_CHECKPOINT_MAX_DELAY_MS fault budget - left
 * unchanged, that tightness is correct and load-bearing for catching a
 * genuinely dead peer within one cycle) against a link that could not yet
 * possibly answer. Raised to comfortably exceed that ~12s worst case
 * rather than "one handshake+round-trip on a healthy link" - the
 * receive()-triggered strong signal (ab_gp_channel_io_check_checkpoint_reenable()
 * called with got_data=true) still re-arms immediately the moment real
 * data proves the peer is actually back, so this deadline is only ever
 * reached in the deadlock-of-last-resort case the comment above already
 * describes, not on the common path. */
#define RTE_EXAMPLE_CHECKPOINT_REENABLE_GRACE_MS 15000U
 
/* Channel-down -> REBOOT threshold for a site's OWN internal redundant
 * channels (the A<->B same-site peer link, and each of A/B's own links
 * to/from C) - deliberately NOT applied to the inter-site negotiation
 * link (A-WEST<->A-EAST etc.), which needs different handling since it
 * connects two DIFFERENT sites: a link outage looks the same from both
 * ends, so rebooting on negotiation-link-down alone would reboot both
 * sites together, achieving the opposite of failover (see ADR-027's own
 * note on this and ab_gp_channel_negotiate.c's standby_hot handling
 * instead). A same-site channel losing contact with its OWN redundant
 * pair, in contrast, is unambiguous local damage - the same reasoning
 * that already justifies REBOOT on a genuine cross-compare DISAGREE
 * (ab_gp_channel_crosscompare.c). Deliberately much longer than
 * RTE_EXAMPLE_LINK_STALE_TIMEOUT_COUNT's own reconnect-trigger
 * threshold (~2 * RTE_EXAMPLE_LINK_TIMEOUT_MS = 6s): a channel that
 * is merely reconnecting should get real time to recover on its own
 * first, and this is deliberately generous enough to tolerate the known,
 * still-open ADR-027 Phase 2 reconnect-livelock scenario turning into a
 * bounded reboot rather than a rare successful self-heal, without firing
 * on routine, short-lived reconnects.
 *
 * ADR-029 addendum #2 (attempted, REVERTED): a matching 20000ms ->
 * 60000ms raise was tried alongside RTE_EXAMPLE_LINK_TIMEOUT_MS's own
 * attempted 3000ms -> 5000ms raise, to keep this constant's "deliberately
 * much longer than" relationship to RTE_EXAMPLE_LINK_STALE_TIMEOUT_COUNT/
 * RTE_EXAMPLE_AB_DUAL_TRANSFER_TIMEOUT_MS intact rather than letting
 * it silently invert. Reverted along with that whole addendum #2 attempt
 * (see RTE_EXAMPLE_LINK_TIMEOUT_MS's own doc - found to regress local
 * stability). Kept at 20000ms. */
#define RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS 20000U
 
/* Consecutive missed-ACK cycles the inter-site negotiation link tolerates
 * before tearing itself down for reconnect (ab_gp_channel_negotiate.c). Under
 * UDP a single dropped datagram is a routine, expected event even on a
 * healthy link (no transport-level retransmission) - rebuilding the link
 * on every miss would reset rte_dual_negotiator_t's tie-break state
 * machine far more often than a real fault warrants. Kept small: this link
 * genuinely needs to notice a dead/restarted peer promptly (ADR-027). */
#define RTE_EXAMPLE_NEG_SEND_MISS_THRESHOLD 3U
 
/* A/B cyclic executive: rte_appmanager_run() loops forever
 * (max_iterations = 0U), one execute() call = one simulated cycle,
 * paced by a real periodic rte_timer rather than free-running as fast as
 * the link allows - see ab_gp_channel.c's file header for the full phase
 * breakdown (read channels / check timers / check tasks / process data /
 * cross-compare / prepare data / dual transfer / send to C). Watchdog
 * timeout is a generous multiple of the cycle period: two independently
 * free-running timers (A's and B's, not synchronized to each
 * other) will legitimately skew by more than one cycle under jitter
 * without that being a real fault.
 *
 * ADR-029 addendum: raised 500ms -> 800ms after live 11-container Docker
 * testing kept reproducing RTE_EXAMPLE_AB_CHECKPOINT_MAX_DELAY_MS
 * misses (REQ-COMMON-SAFESTATE-002 halt/reboot, no retry by design) during
 * otherwise-healthy steady-state operation - not right after a reconnect,
 * where RTE_EXAMPLE_AB_CHECKPOINT_RELAXED_MAX_DELAY_MS already covers
 * it. Host-level scheduling jitter from 11 containers sharing one Docker
 * host (confirmed NOT raw per-container CPU starvation - `docker stats`
 * stayed under 1.2% CPU throughout) has nowhere else to be absorbed: the
 * checkpoint's own steady-state budget is deliberately tight (see that
 * constant's own doc) and is the one window active during normal
 * operation with no wider fallback. Every timing constant derived FROM
 * this one (WATCHDOG_TIMEOUT_MS, DUAL_TRANSFER_TIMEOUT_MS, the
 * negotiation watchdog) scales up proportionally as a result, which is
 * the intended effect, not a side effect - this is the one base unit the
 * whole AB timing hierarchy multiplies from, so widening it here widens
 * jitter tolerance everywhere at once rather than requiring each derived
 * constant to be re-tuned independently. Slower overall AB cadence (more
 * latency on position-report/MA-grant forwarding to C) is the accepted
 * trade-off; confirmed against safeAPITestEnv's own Robot suite that no
 * test timeout is tightly coupled to the old 500ms value (rbc_scenario's
 * own PROPAGATION_TIMEOUT is 40s, ~50x this period even after the
 * raise).
 *
 * ADR-029 addendum #2 (attempted, REVERTED): live GitHub Actions CI
 * testing (standard 2-vCPU hosted runner, not a local developer machine)
 * found A/WEST still repeatedly hitting BOTH
 * RTE_EXAMPLE_AB_CHECKPOINT_MAX_DELAY_MS misses AND separate
 * inter-site negotiation watchdog timeouts every 15-20s of real
 * wall-clock time, well into otherwise-healthy steady-state operation,
 * not just at startup - confirmed via this run's own attached container
 * logs (ContainerLogAttachListener.py), not inference. Raising this
 * 800ms -> 2000ms (and RTE_EXAMPLE_AB_CHECKPOINT_MAX_DELAY_MS/
 * RTE_EXAMPLE_LINK_TIMEOUT_MS/RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS
 * alongside it) was tried, but found live to REGRESS this project's own
 * previously rock-solid local Robot suite (11/11 -> 6/11 on the SAME
 * machine, SAME code, only these constants changed - confirmed by
 * reverting just the constants and re-running, 11/11 again). Reverted;
 * kept at 800ms.
 *
 * Working theory for why widening made things WORSE rather than better:
 * this constant is the ONE base unit checkpoint's own steady-state
 * budget, the AppManager watchdog, dual-transfer-lost detection, and the
 * negotiation watchdog all derive from - widening it doesn't just buy
 * more jitter tolerance, it also lengthens how long EVERY OTHER phase of
 * one AB cycle (read channels/check timers/check tasks/process data/
 * cross-compare/prepare data/dual transfer/send to C, all sharing
 * ctx->peer_send_mutex with the checkpoint's own request/reply) is
 * ALLOWED to run before the next cycle tick fires - on a genuinely
 * busier system this plausibly gives contention on that shared mutex
 * more opportunity to compound cycle-over-cycle instead of draining,
 * rather than simply absorbing one-off jitter the way the FIRST addendum
 * (500ms -> 800ms, kept - see below) did on a less contended local
 * machine. Not fully root-caused live (would need attaching to a
 * genuinely CI-equivalent contended environment to confirm) - the
 * CI-side instability this addendum was meant to fix remains OPEN;
 * fixing it belongs at the CI-environment layer (a less contended
 * runner, or a retry around the whole Robot suite step) rather than by
 * further widening a constant already shown to regress local stability
 * when pushed further in this direction. */
#define RTE_EXAMPLE_AB_CYCLE_PERIOD_MS  500U
#define RTE_EXAMPLE_AB_WATCHDOG_TIMEOUT_MS 600U
 
/* ADR-019 addendum (safeAPIFreamwork): bound on the built-in AppManager
 * checkpoint rendezvous (rte_appmanager_checkpoint_config_t::max_delay_ms,
 * forwarded to rte_checkpoint_config_t::max_delay_ms), run once at the
 * start of every A<->B cycle before pre_execute()/execute()/post_execute()
 * - see ab_gp_channel.c's file header. Sized well under
 * RTE_EXAMPLE_AB_CYCLE_PERIOD_MS so a slow-but-still-alive peer costs
 * cycle latency, not most of the cycle itself, while still being
 * comfortably longer than one round-trip on a healthy localhost link.
 * ADR-027: raised from 150ms (a value tuned for TCP's near-instant
 * connection establishment) once the netlink transport moved to UDP - a
 * freshly-opened or just-reconnected link now converges through a
 * retry-based HELLO handshake (rte_posix_osadapter_netlink.c) rather than
 * a single accept()/connect(), so the very first rendezvous after a link
 * (re)establishes can take longer even though steady-state round-trip
 * latency is unchanged (sub-millisecond on a healthy localhost link).
 * Further raised 300ms -> 450ms after real 6-container Docker testing
 * (not just loopback) of the ADR-027 Phase 2 staleness-reconnect trigger:
 * a live peer-restart-and-reconnect has more jitter than a clean startup
 * - the reconnecting side's own checkpoint is re-enabled the instant its
 * link reopens, racing the first real round trip on a link that just
 * came back, on top of real bridge-network latency loopback testing does
 * not exercise. Still bounded (well under a full cycle, at 90% of
 * RTE_EXAMPLE_AB_CYCLE_PERIOD_MS) - a genuinely dead peer still halts
 * within one cycle, this only gives a *just-reconnected* one more room
 * before that mandatory reaction fires.
 *
 * ADR-029 addendum: raised 450ms -> 700ms alongside
 * RTE_EXAMPLE_AB_CYCLE_PERIOD_MS's own 500ms -> 800ms raise (see that
 * constant's own doc for the full root-cause writeup: live Docker testing
 * found this steady-state budget - the one checkpoint window with no
 * wider "just reconnected" fallback - being missed under ordinary
 * 11-container host jitter, not just after a reconnect). Kept
 * proportionate (87.5% of the new 800ms cycle, still comfortably under a
 * full cycle so a genuinely dead peer is still caught within one cycle),
 * but the absolute slack this buys is real: 250ms of headroom instead of
 * the old 50ms (450 of 500).
 *
 * ADR-029 addendum #2 (attempted, REVERTED): a matching 700ms -> 1800ms
 * raise was tried alongside RTE_EXAMPLE_AB_CYCLE_PERIOD_MS's own
 * attempted 800ms -> 2000ms raise - see that constant's own doc for the
 * live CI evidence AND why the whole attempt was reverted (regressed
 * local stability, 11/11 -> 6/11 on the same machine/code). Kept at
 * 700ms. */
#define RTE_EXAMPLE_AB_CHECKPOINT_MAX_DELAY_MS 400U
 
/* ADR-029 section 2.6 addendum: widened checkpoint budget used ONLY for a
 * bounded window right after the peer link reconnects
 * (ab_gp_channel_types.h's checkpoint_relaxed_until_ms) - NOT a replacement
 * for RTE_EXAMPLE_AB_CHECKPOINT_MAX_DELAY_MS's own steady-state 450ms,
 * which stays tight and load-bearing for catching a genuinely dead peer
 * within one cycle. Found live, with rte_checkpoint.c's own new
 * diagnostic message (registered via a RTE_SAFESTATE_LEVEL_SAFE handler
 * that previously did not exist anywhere in either project, so this
 * REQ-COMMON-SAFESTATE-002 halt was completely silent until now): a real
 * `docker restart` of the peer container - not just the milder link-blip
 * RTE_EXAMPLE_CHECKPOINT_REENABLE_GRACE_MS already handles - produces
 * exactly last_send=RTE_STATUS_OK / last_recv=RTE_STATUS_TIMEOUT, i.e.
 * the reconnected peer is reachable and the request delivered, it simply
 * did not reply within 450ms under the genuine scheduling jitter a full
 * container restart causes on this host. Set generously (well over the
 * measured single-attempt miss) since this window only relaxes latency
 * tolerance for a peer already proven reachable, not the "is this peer
 * even there" question RTE_EXAMPLE_CHECKPOINT_REENABLE_GRACE_MS/
 * checkpoint_pending_reenable's own strong/weak signals already gate on
 * separately. */
#define RTE_EXAMPLE_AB_CHECKPOINT_RELAXED_MAX_DELAY_MS 10000U
 
/* How long RTE_EXAMPLE_AB_CHECKPOINT_RELAXED_MAX_DELAY_MS stays in
 * effect after the peer link's checkpoint is re-armed (see
 * checkpoint_relaxed_until_ms's own doc) before reverting to the normal
 * tight budget. Deliberately similar magnitude to
 * RTE_EXAMPLE_CHECKPOINT_REENABLE_GRACE_MS (15s) - both exist to
 * absorb the same real-world recovery churn window, just at different
 * layers (whether the checkpoint runs at all vs. how long it is willing
 * to wait once it does). */
#define RTE_EXAMPLE_CHECKPOINT_RELAX_DURATION_MS 15000U
 
/* Jitter-tolerant "lookback" for the built-in AppManager checkpoint
 * rendezvous (ab_gp_channel_checkpoint.c). The rendezvous is a synchronous
 * A->B->A round trip run as AppManager stage 4 (last), but the peer can
 * only answer from its OWN next pre_execute(), so a fresh round trip needs
 * >= one full RTE_EXAMPLE_AB_CYCLE_PERIOD_MS - more than
 * RTE_EXAMPLE_AB_CHECKPOINT_MAX_DELAY_MS's steady-state budget allows.
 * It therefore only ever completed in-window when host scheduling jitter
 * was low enough to keep the two cycle phases aligned (true on a quiet
 * dev box, false on a loaded CI runner / VM - see
 * docs/TIMING_AND_DATA_LOSS_ANALYSIS.md finding 10, and the long revert
 * history on RTE_EXAMPLE_AB_CYCLE_PERIOD_MS for why simply widening
 * the budget was rejected).
 *
 * With lookback, this cycle's rendezvous confirms if the peer exchanged
 * ANY checkpoint frame (its own request, or a reply echoing ours) with us
 * within the last N cycles - a local check against a cycle counter, immune
 * to sub-cycle phase. A genuinely silent/partitioned peer still fails the
 * rendezvous after N+1 checkpoint-quiet cycles (~1.5s at N=2), so the
 * bounded reaction REQ-CHECKPOINT-003 requires is preserved, just measured
 * in cycles rather than a sub-cycle millisecond window. Same-program-path
 * divergence (as opposed to liveness) is caught independently and every
 * cycle by the cross-comparator (ab_gp_channel_crosscompare.c), not by
 * this rendezvous. */
#define RTE_EXAMPLE_AB_CHECKPOINT_LOOKBACK_CYCLES 2U
 
/* "Message and acknowledgment" liveness for the A<->B peer link: every
 * cycle each side already sends its own sample AND receives the other's
 * (ab_gp_channel.c's "dual transfer" phase) - that existing exchange already
 * constitutes an implicit request/ack round-trip, so no separate ack-only
 * message type is introduced. This is the timeout on THAT round-trip
 * being usable (decoded + CRC-verified) at least once per window - a
 * dedicated RTE_WATCHDOG_ACTION_FAILOVER watchdog (see ab_gp_channel.c) is
 * kicked only when a usable peer sample actually arrives; going this long
 * without one means the redundant peer is no longer answering, and this
 * site's own channel drops from dual (2oo2) to single-channel mode rather
 * than continuing to assume a partner that is not there. A shorter window
 * than RTE_EXAMPLE_AB_WATCHDOG_TIMEOUT_MS (which only proves the link
 * itself is still up, not that USABLE data is flowing - see
 * docs/TIMING_AND_DATA_LOSS_ANALYSIS.md finding 6) so the degradation is
 * noticed promptly rather than only after the coarser link watchdog would
 * also have fired.
 *
 * ADR-029: raised the multiplier from 6 to 20 for the same reason
 * RTE_EXAMPLE_AB_CYCLE_SKEW_TOLERANCE was raised (see that constant's
 * own doc) - a "usable peer sample" is now only produced once per real
 * train/IL activity (roughly once per sims/train_sim.py's own
 * RTE_EXAMPLE_SIM_PERIOD_SECONDS, 2000ms default), not every AB
 * cycle. The old 6x/3000ms window was already tight against that once
 * any jitter/staggered-train-arrival was added on top - found live as a
 * genuine, non-obvious REBOOT/single-mode flapping loop (both channels
 * see each other as intermittently "gone", entering SINGLE mode, then
 * catching the resulting NEGOTIATION MISMATCH against their own peer's
 * differently-timed flap - RTE_EXAMPLE_REASON_AB_SITE_STATE_MISMATCH).
 * This watchdog's own job is still "is my redundant peer's data usably
 * flowing at all", not "did it flow this exact cycle" - a generous
 * window here costs a slower single-mode reaction to a GENUINELY dead
 * peer, not correctness. */
#define RTE_EXAMPLE_AB_DUAL_TRANSFER_TIMEOUT_MS (RTE_EXAMPLE_AB_CYCLE_PERIOD_MS * 20U)
 
/* C-side counterpart of the above: how many consecutive C report cycles
 * (RTE_EXAMPLE_C_REPORT_PERIOD_MS each) A's forwarded answer may stay
 * byte-for-byte unchanged before monitor_c.c treats A as having gone quiet
 * and falls back to consuming B's forwarded answer instead (see
 * monitor_c.c's rx_b_task_entry()/monitor_c_execute() - B is normally
 * received and discarded, since only A forwards in dual mode; this is what
 * lets B's own SINGLE-mode solo forwarding, see ab_gp_channel.c's
 * on_dual_transfer_lost(), actually reach C when A - not B - is the
 * channel that lost its peer). Sized off the same
 * RTE_EXAMPLE_AB_DUAL_TRANSFER_TIMEOUT_MS window, just expressed in
 * C's own 600ms cycles rather than A/B's 500ms ones (5 cycles @ 600ms =
 * 3000ms, matching the 6 cycles @ 500ms A/B itself uses) - both sides
 * notice a lost A at roughly the same wall-clock delay. */
#define RTE_EXAMPLE_C_A_STALE_CYCLE_LIMIT \
    (RTE_EXAMPLE_AB_DUAL_TRANSFER_TIMEOUT_MS / RTE_EXAMPLE_C_REPORT_PERIOD_MS)
 
/* C's own M136 report cadence - deliberately NOT the same as A/B's
 * RTE_EXAMPLE_AB_CYCLE_PERIOD_MS: C is a third, independently
 * free-running cyclic executive (see monitor_c.c), and this project's
 * cross-compare is already designed to tolerate A, B, and C all running
 * on their own unsynchronized clocks (see
 * RTE_EXAMPLE_AB_CYCLE_SKEW_TOLERANCE above) - a deliberately
 * different period here is what actually exercises that, rather than the
 * three processes coincidentally staying in lockstep because they all
 * share one constant. */
#define RTE_EXAMPLE_C_REPORT_PERIOD_MS  600U
 
/* A (LISTEN, starts its cycle timer as soon as its own init() finishes)
 * and B (CONNECT, whose init() additionally retries the peer connect in
 * open_connect_with_retry() before it can start its own cycle timer)
 * start their independent 500ms cycle timers at two different wall-clock
 * moments - not just "occasional jitter" but a roughly FIXED phase skew
 * for the rest of that run (same nominal period afterward, so it does not
 * self-correct). Requiring the peer's stamped cycle number to match
 * one's own EXACTLY would then permanently fail cross-compare on
 * whichever side ends up on the "losing" side of that fixed skew - this
 * tolerance lets cross-compare still proceed when the two sides are
 * within a few cycles of each other (still rejecting a genuinely stale/
 * hung peer as "no comparable data this cycle", just with a wider,
 * skew-tolerant window instead of an exact match).
 *
 * ADR-029: raised from 3 to 20 once real Train sims (not C self-
 * generating M136 every ~600ms) started exercising this - an
 * AB_SAMPLE is now only sent on a cycle that actually had fresh train/IL
 * data (ab_gp_channel_send_peer_sample_if_online()'s have_channel_data gate), which
 * happens roughly once per RTE_EXAMPLE_SIM_PERIOD_SECONDS (2000ms
 * default = ~4 AB cycles at 500ms each), not every cycle - so the
 * embedded cycle number in the SENDER's last AB_SAMPLE can legitimately
 * be several cycles behind the RECEIVER's own current count even on a
 * perfectly healthy link, on top of the original startup-skew this
 * tolerance already existed for. 3 rejected essentially every real
 * cross-compare attempt once trains reported on their own realistic
 * cadence rather than C's old near-every-cycle heartbeat - found live.
 * This is purely "is this specific sample still worth comparing", not a
 * liveness check (a genuinely dead peer is caught by
 * ctx->dual_transfer_watchdog/RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS
 * instead - both scoped to actual silence, not sample age) - a generous
 * value here costs nothing but a slightly wider "still comparable"
 * window. */
#define RTE_EXAMPLE_AB_CYCLE_SKEW_TOLERANCE 20U
 
/* ADR-029: bounds how many consecutive AB cycles
 * ab_gp_channel_crosscompare_execute() will skip (not disagree) a single
 * train whose session does not yet match its peer's, before treating it
 * as a genuine divergence instead of an ordinary asynchronous-arrival
 * timing race - see that function's own doc. 10 cycles (~5s at
 * RTE_EXAMPLE_AB_CYCLE_PERIOD_MS) is comfortably longer than the
 * relay latency a healthy link needs to bring both channels' session
 * tables back into agreement, while still well under
 * RTE_EXAMPLE_AB_DUAL_TRANSFER_TIMEOUT_MS/RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS's
 * own much longer windows - a real, permanent divergence (e.g. a lost
 * ROUTE_ADD relay datagram - see monitor_c.c's relay_inbound_to_ab() own
 * doc) is still detected and reacted to promptly, not silently ignored
 * forever. */
#define RTE_EXAMPLE_XCOMPARE_SYNC_SKIP_LIMIT 10U
 
/* Inter-site negotiation: how often each of A's and B's own negotiate
 * step (ab_gp_channel.c, folded from the old standalone SITE role - see
 * that file's header) drives its rte_dual_negotiator_execute() call and
 * exchanges the extra payload below with its own counterpart on the
 * other site. Reuses the same cadence as the A/B cycle itself
 * (RTE_EXAMPLE_AB_CYCLE_PERIOD_MS) - no separate timer, since
 * negotiation is now just one more step inside that same cycle, not a
 * standalone process with its own heartbeat rate.
 *
 * Watchdog timeout: MUST stay longer than the worst case time
 * RTE_EXAMPLE_NEG_SEND_MISS_THRESHOLD's own hysteresis (
 * ab_gp_channel_negotiate.c) needs to detect a dead link, close it, and get
 * a fresh reconnect's first send through - otherwise this watchdog (which
 * reboots the ONLINE side outright on expiry, see
 * RTE_EXAMPLE_REASON_NEGOTIATION_LINK_LOST) fires and reboots on the
 * very first missed ACK, before the hysteresis it's layered on top of
 * ever gets a chance to run - found live (ADR-027): a single dropped UDP
 * datagram's own ack_timeout_ms wait (RTE_EXAMPLE_LINK_TIMEOUT_MS)
 * alone already exceeded the previous fixed 2500ms value here, defeating
 * the hysteresis entirely. Derived, not a bare constant, specifically so
 * the two can never drift back out of sync silently: worst case is
 * RTE_EXAMPLE_NEG_SEND_MISS_THRESHOLD full ACK-wait timeouts before
 * the hysteresis closes the link, plus one reconnect attempt, plus one
 * more cycle for that reconnect's first send to land and kick this
 * watchdog. */
#define RTE_EXAMPLE_NEGOTIATION_WATCHDOG_TIMEOUT_MS                                 \
    ((RTE_EXAMPLE_NEG_SEND_MISS_THRESHOLD * RTE_EXAMPLE_NEG_ACK_TIMEOUT_MS) +       \
     RTE_EXAMPLE_RECONNECT_ATTEMPT_TIMEOUT_MS + RTE_EXAMPLE_AB_CYCLE_PERIOD_MS)
 
/* This site's own live ONLINE/STANDBY/FAULTED role, negotiated by A and
 * B themselves (ab_gp_channel.c's own "negotiate" step - see that file's
 * header) and carried directly as in-memory state (ctx->is_online/
 * ctx->own_faulted) and inter-site wire messages - no shared filesystem
 * assumption between containers (each of A, B, and C is a genuinely
 * separate container/machine - see README's "6 containers" section).
 *
 * Three role states, not two: FAULTED is distinct from STANDBY so the
 * live-failover protocol cannot flap. When ab_gp_channel.c's cross-compare
 * detects a genuine M24/M15 disagreement, it sets ctx->own_faulted and
 * enters RTE_SAFESTATE_LEVEL_REBOOT - it never just falls back to
 * STANDBY for this, specifically so the peer site's own negotiate step
 * can tell "peer just faulted" apart from "peer has always been
 * standby." The promotion rule is: a STANDBY channel promotes itself to
 * ONLINE once its own inter-site link reports the peer FAULTED - a
 * FAULTED channel itself never self-promotes, which is what breaks the
 * would-be flapping loop of both sides re-negotiating back and forth. */
#define RTE_EXAMPLE_SITE_ROLE_ONLINE      1U
#define RTE_EXAMPLE_SITE_ROLE_STANDBY     0U
#define RTE_EXAMPLE_SITE_ROLE_FAULTED     2U
#define RTE_EXAMPLE_SITE_ROLE_VALID_MARKER 0xA5U
#define RTE_EXAMPLE_SINGLE_MODE_FLAG_DUAL   0U 
#define RTE_EXAMPLE_SINGLE_MODE_FLAG_SINGLE 1U 
 
/* ---------------------------------------------------------------------
 * Online->standby state transfer (ab_gp_channel.c's "negotiate" step)
 * ---------------------------------------------------------------------
 * Carried directly in the inter-site negotiation payload below, with no
 * NVM round-trip: the channel that is ONLINE already has ctx->cyc_cycle
 * and its own live ctx->sessions[] (ADR-029 - a whole train-session
 * table) in memory every cycle and includes them directly in what it
 * sends to its own
 * inter-site counterpart. On a STANDBY->ONLINE promotion, the configured
 * transfer policy (RESTART/CONTINUE/ASK_USER) is applied to ctx->cycle
 * from the most recently cached counterpart snapshot, while ctx->sessions[]
 * itself is applied unconditionally (REQ-RBC-006) - see
 * ab_gp_channel_negotiate.c's own apply_state_transfer(). */
 
/* Inter-site negotiation payload (rte_dual_channel_send()/_receive(),
 * separate from the negotiator's own STATE-frame traffic - see
 * ab_gp_channel.c's own doc): relays this channel's own current FAULTED/
 * single-mode status (the negotiator's own rte_dual_state_t has no
 * FAULTED value, see ab_gp_channel.c's own design note) together with the
 * state-transfer snapshot, in one combined per-cycle send instead of
 * several.
 *
 * ADR-029: the state-transfer snapshot carries the whole train-session
 * table (RTE_EXAMPLE_MAX_TRAINS entries) - a promoted STANDBY site
 * must already know every connected train's granted MA length/sequence
 * (see ab_gp_channel_negotiate.c's encode_extra_payload()/
 * decode_extra_payload() and monitor_c.c's file header for why C is a
 * pure relay with no self-generated M136). `cycle` stays a standalone scalar field
 * (THIS CHANNEL's own next-AB-cycle-to-run counter, unrelated to any
 * train's own M136 cycle number - see ab_gp_channel_types.h's own
 * neg_peer_extra doc). Per-session encoding: in_use(1) + train_id(1) +
 * cycle(4) + d_lrbg(4) + granted_length(4) + ma_seq(4) + ma_acked(1) = 19
 * bytes. Well under rte_vital_message_t's 248-byte payload capacity
 * (rte_checksum.h) that this ultimately rides inside via
 * rte_dual_channel_send() - no framework-side size ceiling anywhere
 * near this. */
#define RTE_EXAMPLE_DB_ROUTE_WIRE_SIZE 12U
#define RTE_EXAMPLE_DB_TRAIN_WIRE_SIZE 16U
#define RTE_EXAMPLE_DB_WIRE_SIZE \
    ((RTE_EXAMPLE_MAX_ROUTES * RTE_EXAMPLE_DB_ROUTE_WIRE_SIZE) + \
     (RTE_EXAMPLE_MAX_TRAINS * RTE_EXAMPLE_DB_TRAIN_WIRE_SIZE))
 
#define RTE_EXAMPLE_SITE_EXTRA_PAYLOAD_SESSION_SIZE 19U /* one ab_gp_train_session_t, encoded */
#define RTE_EXAMPLE_SITE_EXTRA_PAYLOAD_SIZE \
    (2U + 4U + (RTE_EXAMPLE_MAX_TRAINS * RTE_EXAMPLE_SITE_EXTRA_PAYLOAD_SESSION_SIZE) + \
     RTE_EXAMPLE_DB_WIRE_SIZE + 1U) /* faulted(1) + single_mode(1) + cycle(4) + sessions[] + db + valid(1) */
 
 
/* Local A<->B cross-check payload (PEER_MSG_KIND_SITE_STATE - see
 * ab_gp_channel_types.h): each side's own independently-negotiated
 * {is_online, single_mode}, exchanged over the SAME existing peer link
 * every cycle so A and B can confirm their two independent inter-site
 * negotiation links (above) agree - a mismatch is itself a fault (see
 * ab_gp_channel_crosscompare.c). */
#define RTE_EXAMPLE_AB_SITE_STATE_WIRE_SIZE 3U /* is_online(1) + single_mode(1) + ready_for_online(1) */

typedef enum
{
    RTE_EXAMPLE_TRANSFER_POLICY_RESTART  = 0, 
    RTE_EXAMPLE_TRANSFER_POLICY_CONTINUE = 1, 
    RTE_EXAMPLE_TRANSFER_POLICY_ASK_USER = 2  
} rte_example_transfer_policy_t;

#define RTE_EXAMPLE_TRANSFER_POLICY_ENV "RTE_EXAMPLE_TRANSFER_POLICY"

#define RTE_EXAMPLE_TRANSFER_ASK_USER_TIMEOUT_MS 2000U
 
/* CRC-64 polynomial used for the A<->B peer link's integrity check
 * (ab_gp_channel.c) - ERTMS per this codebase's own naming (see
 * safeAPIFreamwork/src/checksum/rte_checksum.c's file-level note: there
 * is no publicly standardized "CRC-64/ERTMS"; this is this project's own
 * convention, matching its railway/CENELEC domain). */
#define RTE_EXAMPLE_CRC64_POLYNOMIAL RTE_CRC64_ERTMS
 
/* Application-specific safe-state reason code: the A<->B peer link's
 * received CRC-64 does not match the data actually received (see
 * RTE_SAFESTATE_REASON_APPLICATION_BASE's doc in rte_safestate.h -
 * values below it are reserved for the framework itself). This means
 * either transmission corruption or a peer that computed a differently-
 * sized/shaped message than expected; either way it is not the ordinary
 * "peer computed a different message type" disagreement ab_gp_channel.c also
 * detects and reports (DISAGREE) - a broken CRC means the peer's message
 * cannot be trusted at all, which ab_gp_channel.c treats as a fault requiring
 * RTE_SAFESTATE_LEVEL_SAFE, not a loggable disagreement. */
#define RTE_EXAMPLE_REASON_AB_CRC_MISMATCH \
    ((rte_safestate_reason_t)(RTE_SAFESTATE_REASON_APPLICATION_BASE + 1U))
 
/* Application-specific safe-state reason code: A and B independently
 * decided a different M24/M15 message type for the same M136 position
 * report cycle (both messages individually verified fine over CRC-64 - see
 * RTE_EXAMPLE_REASON_AB_CRC_MISMATCH above for the distinct "cannot be
 * trusted at all" case). A CRC-clean *disagreement in meaning* is judged
 * severe: per the RBC simulation this project models, a channel that
 * computed the wrong movement-authority decision cannot be allowed to
 * keep influencing the live output, so this escalates all the way to
 * RTE_SAFESTATE_LEVEL_REBOOT (see ab_gp_channel.c and
 * ab_gp_channel_negotiate.c's failover protocol), not just SAFE. */
#define RTE_EXAMPLE_REASON_AB_MTYPE_DISAGREE \
    ((rte_safestate_reason_t)(RTE_SAFESTATE_REASON_APPLICATION_BASE + 2U))
 
/* Application-specific safe-state reason code: this channel's own
 * inter-site negotiation link watchdog (ab_gp_channel_negotiate.c) fired -
 * the message-and-acknowledgment round-trip with this channel's own
 * counterpart on the other site (send this cycle's extra payload, receive
 * theirs) has not completed successfully for
 * RTE_EXAMPLE_NEGOTIATION_WATCHDOG_TIMEOUT_MS - AND this channel
 * currently considers itself ONLINE (see
 * ab_gp_channel_negotiate.c's own on_negotiation_link_lost() - a STANDBY
 * channel losing this same link does NOT reboot, since that is the
 * ordinary, expected shape of its ONLINE counterpart's own planned
 * fault->reboot cycle, not a fault of its own). For the ONLINE side,
 * losing this link is judged serious: it is the only channel through
 * which the two sites' A (or both B) agree on who is ONLINE, so an ONLINE
 * channel that can no longer prove it is healthy (or relay a future
 * fault) risks an undetected split-brain (both sides independently
 * believing they should be ONLINE) rather than just reduced redundancy.
 * This escalates all the way to RTE_SAFESTATE_LEVEL_REBOOT - setting
 * ctx->own_faulted first, same idiom as
 * RTE_EXAMPLE_REASON_AB_MTYPE_DISAGREE, so the peer's own existing
 * promotion rule can react to it exactly as it already does for an A/B-
 * detected fault, and this channel self-recovers via the same already-
 * verified mock-reboot mechanism rather than halting forever (a bare
 * RTE_SAFESTATE_LEVEL_SAFE here would have no REBOOT handler to recover
 * it - see main.c). Honest limitation: once lost, this link itself does
 * not auto-reconnect - only a subsequent reboot of this process (its
 * own fault, or this same watchdog) reopens it. */
#define RTE_EXAMPLE_REASON_NEGOTIATION_LINK_LOST \
    ((rte_safestate_reason_t)(RTE_SAFESTATE_REASON_APPLICATION_BASE + 3U))
 
/* Application-specific safe-state reason code: A's and B's own
 * independently-negotiated {is_online, single_mode} (each computed via its
 * own separate inter-site negotiation link - see ab_gp_channel_negotiate.c)
 * disagree, as cross-checked over the existing local A<->B peer link
 * (PEER_MSG_KIND_SITE_STATE) - see ab_gp_channel_crosscompare.c's own
 * negotiation-mismatch reaction. Treated the same as a genuine M24/M15
 * DISAGREE (RTE_EXAMPLE_REASON_AB_MTYPE_DISAGREE): this is a judgment
 * call trading some availability for never letting A and B act on a
 * disagreed site-role - a single degraded inter-site link (not necessarily
 * a real split-brain) can also trigger this reboot. */
#define RTE_EXAMPLE_REASON_AB_SITE_STATE_MISMATCH \
    ((rte_safestate_reason_t)(RTE_SAFESTATE_REASON_APPLICATION_BASE + 4U))
 
/* Application-specific safe-state reason code: this channel's own
 * same-site peer link (A<->B) has been unable to communicate with its
 * own redundant pair for RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS
 * continuously (see ab_gp_channel_io.c's peer rx task, and that constant's
 * own doc for why this is unambiguously local damage, unlike the
 * inter-site negotiation link - RTE_EXAMPLE_REASON_NEGOTIATION_LINK_LOST
 * above already covers that separately, with its own ONLINE-only
 * reasoning). A site whose own A and B cannot reach each other has lost
 * its own internal cross-compare integrity check entirely, not just one
 * cycle's worth of data - the same severity judgment as a genuine
 * DISAGREE (RTE_EXAMPLE_REASON_AB_MTYPE_DISAGREE), just detected via
 * transport failure instead of a content mismatch. */
#define RTE_EXAMPLE_REASON_AB_PEER_LINK_DOWN \
    ((rte_safestate_reason_t)(RTE_SAFESTATE_REASON_APPLICATION_BASE + 5U))
 
/* Application-specific safe-state reason code: this channel's own link
 * to/from C has been unable to communicate for
 * RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS continuously (see
 * ab_gp_channel_io.c's M136 rx task). Without C, this channel has no
 * M136/D_LRBG input at all and cannot produce a movement-authority
 * decision - the same "cannot keep operating without this channel"
 * judgment as RTE_EXAMPLE_REASON_AB_PEER_LINK_DOWN above, just for
 * the other of this channel's two external links. */
#define RTE_EXAMPLE_REASON_C_LINK_DOWN \
    ((rte_safestate_reason_t)(RTE_SAFESTATE_REASON_APPLICATION_BASE + 6U))
 
/* Application-specific safe-state reason code, C's own side
 * (monitor_c_io.c): this instance of C has been unable to reach A (or B)
 * for RTE_EXAMPLE_CHANNEL_DOWN_REBOOT_MS continuously. Note this does
 * NOT itself drive site failover the way an A/B reboot does (C is not a
 * party to the inter-site ONLINE/STANDBY negotiation - see
 * ab_gp_channel_negotiate.c) - this is purely "C's own link is broken badly
 * enough that a fresh process/socket state is more likely to recover
 * than continuing to retry the same one", not a failover trigger. */
#define RTE_EXAMPLE_REASON_C_MONITOR_LINK_DOWN \
    ((rte_safestate_reason_t)(RTE_SAFESTATE_REASON_APPLICATION_BASE + 7U))
 
/* ---------------------------------------------------------------------
 * RBC (Radio Block Centre) train-position-report simulation
 * ---------------------------------------------------------------------
 * Each connected Train sim cyclically reports its own position (M136,
 * D_LRBG) via C to A/B (ADR-029: relayed by C, a pure relay - see
 * monitor_c.c's own file header for why). Every M136 gets a plain M24
 * ack, unconditionally, unless this train has some other message due
 * this same cycle instead (e.g. a pending M3 Movement Authority grant,
 * sent as an ADDITIONAL output alongside the M24 ack - see
 * ab_gp_train_build_outputs()). Only A forwards the agreed answer to C
 * (B's own agreeing answer is redundant once cross-compare confirms it
 * matches A's - see ab_gp_channel.c).
 * RTE_EXAMPLE_MSG_M15/the old RTE_EXAMPLE_DLRBG_THRESHOLD
 * D_LRBG-based M24-vs-M15 decision were RETIRED on direct request - M15
 * here never represented a real Subset-026 Conditional Emergency Stop
 * trigger, just this simulated ack arbitrarily picking a different
 * message kind past a distance threshold, with no operational meaning
 * behind the switch. The real Subset-026 Msg 15 encoder
 * (ab_gp_proc_emergency_stop_issue_ces(), ertms_procedures/) is
 * unaffected - it already has no callers on this flat scheme's own
 * path. */
#define RTE_EXAMPLE_MSG_M136 136U
#define RTE_EXAMPLE_MSG_M24  24U
 
/* ---------------------------------------------------------------------
 * RBC Train/IL/CTC scenario (ADR-029) - real Train/IL/CTC TCP clients
 * ---------------------------------------------------------------------
 * Extends the M136/M24 simulation above with a real train identity
 * (P0), a Movement Authority the RBC grants/extends from IL-supplied
 * routes (M3, acked by the train with M146), and one-way status pushes to
 * CTC. See rbc_wire_types.h for the shared envelope struct all of this
 * rides in (one fixed-size struct reused for every kind below, per this
 * project's MISRA fixed-size-everything convention - no variant-length
 * encoding anywhere in this codebase). C (monitor_c.c) is a pure relay
 * for all of these - it does not compute the MA/route decision itself
 * (that is A/B's job, same as the M24 ack decision already is), it only
 * translates between the Train/IL/CTC-facing sockets and the existing
 * C<->A/B link. */
#define RTE_EXAMPLE_MSG_P0    0U   /* Train -> C -> AB: handshake, establishes this session's train_id */
#define RTE_EXAMPLE_MSG_M3    3U   /* AB -> C -> Train: Movement Authority (grant or extend) */
#define RTE_EXAMPLE_MSG_M146  146U /* Train -> C -> AB: MA ack (echoes the acked ma_seq) */
 
/* Amount (in meters) each single IL route-add grants/extends this train's
 * Movement Authority by - "first simple logic pass" (no real route
 * topology/geometry, see ADR-029): every ROUTE_ADD is worth exactly this
 * much, and the RBC's own granted_length is just their running sum. */
#define RTE_EXAMPLE_MA_ROUTE_LENGTH_M 500U
 
/* Overlap / danger-point margin (meters): the End/Limit of Authority
 * (EoA/LOA) the RBC grants sits this far SHORT of the last route's end
 * signal (the Supervised Location). Without it the granted MA length was
 * exactly the balise->end-signal topology distance, so every MA - and
 * the web_runner EoA marker driven by it - ended precisely on a signal,
 * which real ETCS never does. Subtracted ONCE, from the final route's
 * contribution (ab_gp_proc_ma_compute() / the flat-scheme grant in
 * safeAPIRBC2oo2GA's ab_ga_il.c); an MA extension re-targets a new end
 * signal but the single subtraction just carries forward. The robot MA
 * tests read the same value as ${MA_OVERLAP_M} (generated into
 * site_routes.resource). */
/* Currently 0: the overlap is skipped for now (decision 2026-09-21); the MA ends on the end signal. Set it back to a
 * real margin (was 100 m) when the overlap is wanted again - every consumer reads this one constant. */
#define RTE_EXAMPLE_MA_OVERLAP_M 0U
 
/* Wire envelope, all little-endian - see rbc_wire_types.h. REQ-RBC-001
 * (revised, safeAPIFreamwork/docs/requirements/SRS.md): a real
 * Subset-026-style header, present on every kind -
 *   kind(1) + train_id(1) + nid_message(1) + reserved(1) + l_message(2)
 *   + reserved(2) + t_train(4) = 12 bytes
 * - followed by CONTENT, whose length genuinely varies by kind (l_message
 * says how much of this fixed-size slot is actually meaningful; the rest
 * is zero-padding, not sent-as-variable-size-datagrams - see AB/train/
 * ab_gp_train.c's own train_wire_encode() header for why: changing the
 * actual UDP datagram size touches 20+ already-tested
 * rte_netlink_send()/_recv() call sites across ab_gp_channel.c/
 * monitor_c*.c, out of scope for this pass):
 *   cycle(4) + d_lrbg(4) + msg_type(4) + route_len(4) + ma_seq(4) +
 *   ma_length(4) = 24 bytes for every kind (UNCHANGED layout/order - low
 *   risk to already-working decode logic), THEN, always at these same
 *   fixed offsets regardless of kind (no offset aliasing between
 *   different kinds' own extension fields - see AB/train/ab_gp_train.c's
 *   own train_wire_encode() header for why not):
 *     t_train_ack(4) - RBC_MSG_M146 (Acknowledgement) only: real
 *       Subset-026 message 146 acks by echoing this timestamp, not
 *       ma_seq. 0/unused for every other kind.
 *     nid_lrbg(4) + q_dirlrbg(4) + q_dlrbg(4) + l_doubtover(4) +
 *       l_doubtunder(4) + q_length(4) + v_train(4) + q_dirtrain(4) +
 *       m_mode(4) + m_level(4) = 40 bytes - RBC_MSG_M136 (Position
 *       Report) only: the real, flat (no N_ITER/nesting) Subset-026
 *       Packet 0 fields beyond d_lrbg. 0/unused for every other kind.
 *     start_signal(4) + end_signal(4) + route_type(4) + route_status(4)
 *       = 16 bytes, offsets 80-95 - RBC_MSG_ROUTE_ADD/_ROUTE_RELEASE/
 *       _TRAIN_POSITION_IN_ROUTE only: real route identity (the signal
 *       pair a route runs between - safeAPIRBC2oo2GA/include/ab_siteGA.h's own
 *       ab_site_ga_route_layout_t) plus ROUTE_ADD's own supervision-mode
 *       (route_type) and TRAIN_POSITION_IN_ROUTE's own occupancy
 *       (route_status). Appended after the M136 block, same additive-
 *       growth precedent as t_train_ack/the M136 block itself - never a
 *       repurposed existing field. 0/unused for every other kind.
 * l_message says how much of this is actually meaningful for a given
 * envelope's own kind - 36 for most kinds, 40 for RBC_MSG_M146, 80 for
 * RBC_MSG_M136, 96 (the whole slot) for ROUTE_ADD/ROUTE_RELEASE/
 * TRAIN_POSITION_IN_ROUTE - not how many bytes are physically written
 * (always all 96). Max total: 12 + 24 + 4 + 40 + 16 = 96 bytes. This
 * layout is duplicated (not shared) across AB/train/ab_gp_train.c's,
 * AB/GA/il/ab_ga_il.c's, and AB/GA/ctc/ab_ga_ctc.c's own file-static wire codecs -
 * each domain owns encoding/decoding the kinds its own relay channel
 * carries, with no single shared codec (see ab_gp_train.c's own module doc
 * for why). Grown once already this session (80 -> 96, for the IL<->RBC
 * route-identity interface) - SimCore's own byte-identical Python mirror
 * (simcore/rbc_wire.py) MUST be updated in lockstep whenever this changes;
 * see that file's own doc. */
#define RBC_ENVELOPE_WIRE_SIZE 96U
 
/* Train relay channel ONLY (see rbc_wire_types.h's RBC_MSG_ERTMS_ENVELOPE
 * doc): matches ab_gp_ertms_train_message_codec.h's own RBC_TRAIN_MAX_WIRE_MSG_SIZE
 * (512) - RBC_MSG_ERTMS_ENVELOPE's own 2-byte kind+train_id prefix eats
 * into that, leaving 510 bytes for the codec's own frame, comfortably
 * above every real message this codec actually builds in this scope
 * (Msg 3 with every optional packet present is ~180 bytes) and above
 * the codec's own real enforced minimums (32 bytes encode, 11 decode -
 * its header doc's "buffer_size must be >= RBC_TRAIN_MAX_WIRE_MSG_SIZE"
 * is a stale aspiration, not what the code actually checks). Every
 * OTHER kind on the Train channel
 * (P0/M136/M24_M15/M3/M146/TRAIN_DISCONNECT) keeps using the plain
 * RBC_ENVELOPE_WIRE_SIZE shape above, just inside a bigger physically-
 * allocated slot - always sent/read at this full fixed size,
 * zero-padded past whatever's actually meaningful, same "fixed
 * MAXIMUM, a length field says how much is real" philosophy as
 * RBC_ENVELOPE_WIRE_SIZE itself (this project's own UDP transport has
 * no length-prefix framing of its own to lean on instead - see
 * dual_link.py's/rte_posix_osadapter_channel_service.c's own docs).
 * SimCore's own byte-identical Python mirror (simcore/rbc_ertms_wire.py)
 * MUST match this exactly. */
#define RBC_TRAIN_ENVELOPE_WIRE_SIZE 512U
 
/* RTE_EXAMPLE_DLRBG_FAULT_VALUE (was 101U) - RETIRED alongside the
 * M24/M15 D_LRBG-threshold decision above: it forced role A to compute
 * M15 while B kept computing M24 at D_LRBG=101, demonstrating a genuine
 * cross-compare disagreement. With M15 gone, both channels always agree
 * on the M24 ack, so this specific fault-injection path can no longer be
 * triggered this way. The generic cross-compare mechanism itself
 * (ab_gp_channel_crosscompare.c, ctx->own_faulted) is untouched and still
 * catches any OTHER genuine A/B divergence - this only removes the one
 * D_LRBG-driven demo trigger for it. */
 
/* ---------------------------------------------------------------------
 * Mock hardware reboot + live recovery
 * ---------------------------------------------------------------------
 * A real hardware reset is not instantaneous - main.c's REBOOT safe-state
 * handler sleeps this long (with clear "FAULTED, rebooting" logging)
 * before actually re-execing, so a demo run shows the fault -> reboot ->
 * resume sequence as a visible event instead of an instant, easy-to-miss
 * re-exec. */
#define RTE_EXAMPLE_REBOOT_DELAY_MS 5000U
 
#endif /* RTE_EXAMPLE_COMMON_CONFIG_H */