@typecad/cuttlefish 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/safety/runtime/safe-int.d.ts

@@ -0,0 +1,33 @@
+import type { RuntimePolyfillIR } from "../../api/index.js";
+/** SafeInt<T> polyfill: chainable bounds-checked signed-integer arithmetic.
+ *
+ *  Mutating chain — every math op returns SafeInt<T>& so calls compose:
+ *    x.add(5).mul(2).get()
+ *
+ *  Sticky-fault overflow policy: on overflow or division error, set fault_
+ *  and stop computing. Subsequent ops are no-ops returning *this. get()
+ *  returns the last good value. hasFault()/valid() inspect the flag;
+ *  reset() clears it.
+ *
+ *  Overflow detection uses portable pure-C++14 PRE-CHECKS (bounds tests
+ *  before the assignment). The reconstruction trick would compute first
+ *  then check, but the initial computation is signed-overflow UB. Pre-checks
+ *  avoid the UB, work at every width including int64_t (no wider promotion
+ *  type needed), and need no __builtin_*_overflow (a GCC/clang extension
+ *  that would require an AUTOSAR deviation).
+ *
+ *  NO <type_traits> / <limits> includes: AVR's toolchain ships neither
+ *  header. The type constraint (static_assert) and the per-width bounds come
+ *  from the shared hand-rolled __tc_safe_traits block (safe-traits.ts), which
+ *  uses only core-language features (template specialization, static_cast,
+ *  constexpr) that every supported target — including AVR's avr-gcc — has.
+ *
+ *  AUTOSAR C++14 compliance:
+ *  - static_assert on T (rejects unsigned, bool, float, non-integer)
+ *  - noexcept on all methods (A15-0-2)
+ *  - [[nodiscard]] on get/hasFault/valid (A0-1-1)
+ *  - constexpr constructor
+ *  - static_cast throughout (no C-casts M5-0-7, no builtins M5-0-10,
+ *    no malloc A18-5-10). Zero deviations required.
+ */
+export declare function safeIntPolyfill(): RuntimePolyfillIR;

package/dist/safety/runtime/safe-int.js

@@ -0,0 +1,170 @@
+import { emitSafeTraits } from "./safe-traits.js";
+/** SafeInt<T> polyfill: chainable bounds-checked signed-integer arithmetic.
+ *
+ *  Mutating chain — every math op returns SafeInt<T>& so calls compose:
+ *    x.add(5).mul(2).get()
+ *
+ *  Sticky-fault overflow policy: on overflow or division error, set fault_
+ *  and stop computing. Subsequent ops are no-ops returning *this. get()
+ *  returns the last good value. hasFault()/valid() inspect the flag;
+ *  reset() clears it.
+ *
+ *  Overflow detection uses portable pure-C++14 PRE-CHECKS (bounds tests
+ *  before the assignment). The reconstruction trick would compute first
+ *  then check, but the initial computation is signed-overflow UB. Pre-checks
+ *  avoid the UB, work at every width including int64_t (no wider promotion
+ *  type needed), and need no __builtin_*_overflow (a GCC/clang extension
+ *  that would require an AUTOSAR deviation).
+ *
+ *  NO <type_traits> / <limits> includes: AVR's toolchain ships neither
+ *  header. The type constraint (static_assert) and the per-width bounds come
+ *  from the shared hand-rolled __tc_safe_traits block (safe-traits.ts), which
+ *  uses only core-language features (template specialization, static_cast,
+ *  constexpr) that every supported target — including AVR's avr-gcc — has.
+ *
+ *  AUTOSAR C++14 compliance:
+ *  - static_assert on T (rejects unsigned, bool, float, non-integer)
+ *  - noexcept on all methods (A15-0-2)
+ *  - [[nodiscard]] on get/hasFault/valid (A0-1-1)
+ *  - constexpr constructor
+ *  - static_cast throughout (no C-casts M5-0-7, no builtins M5-0-10,
+ *    no malloc A18-5-10). Zero deviations required.
+ */
+export function safeIntPolyfill() {
+    return {
+        kind: "polyfill",
+        id: "safety_safe_int",
+        domain: "embedded",
+        requiredIncludes: [],
+        forwardDeclarations: [],
+        helperStructs: [],
+        helperFunctions: [`
+${emitSafeTraits()}
+
+#ifndef __TC_SAFE_INT_DEFINED
+#define __TC_SAFE_INT_DEFINED
+
+// No #include here: the fixed-width integer types come transitively from
+// <Arduino.h> on embedded targets (which pulls <stdint.h>), mirroring the
+// other safety polyfills (mode-table, vote). The shared __tc_safe_traits
+// block (emitted above) is also header-free.
+
+template <typename T>
+struct SafeInt {
+  static_assert(__tc_safe_traits::is_integral<T>::value
+                && __tc_safe_traits::is_signed<T>::value
+                && !__tc_safe_traits::is_same<T, bool>::value,
+                "SafeInt<T> requires a signed integer T (int8_t/int16_t/int32_t/int64_t). "
+                "Unsigned, bool, floating-point, and non-integer types are rejected.");
+
+private:
+  T value_;
+  bool fault_;
+
+  static constexpr T kMax = __tc_safe_traits::bounds<T>::kMax;
+  static constexpr T kMin = __tc_safe_traits::bounds<T>::kMin;
+
+public:
+  // Default constructor: zero-initialized, no fault. Required because promoted
+  // top-level variables default-construct via '= {}' before their real
+  // initializer is assigned inside the entrypoint. Mirrors SafeVariable's
+  // default ctor.
+  constexpr SafeInt() noexcept : value_(0), fault_(false) {}
+  constexpr SafeInt(T initial) noexcept : value_(initial), fault_(false) {}
+
+  SafeInt<T>& add(T delta) noexcept {
+    if (fault_) { return *this; }
+    // Pre-check: overflow iff (delta>0 && value>Max-delta) || (delta<0 && value<Min-delta).
+    // (Max-delta) and (Min-delta) are safe because delta has the opposite sign
+    // of the bound being approached, so the subtraction cannot itself overflow.
+    if ((delta > 0 && value_ > kMax - delta) || (delta < 0 && value_ < kMin - delta)) {
+      fault_ = true;
+      return *this;
+    }
+    value_ = static_cast<T>(value_ + delta);
+    return *this;
+  }
+
+  SafeInt<T>& sub(T delta) noexcept {
+    if (fault_) { return *this; }
+    // Direct pre-check (NOT add(-delta), since -delta is UB when delta==Min):
+    //   value - delta > Max  iff  value > Max + delta   (when delta < 0)
+    //   value - delta < Min  iff  value < Min + delta   (when delta > 0)
+    // (Max+delta)/(Min+delta) are safe — delta has the opposite sign of the bound.
+    if ((delta < 0 && value_ > kMax + delta) || (delta > 0 && value_ < kMin + delta)) {
+      fault_ = true;
+      return *this;
+    }
+    value_ = static_cast<T>(value_ - delta);
+    return *this;
+  }
+
+  SafeInt<T>& mul(T factor) noexcept {
+    if (fault_) { return *this; }
+    if (factor == 0 || value_ == 0) { value_ = 0; return *this; }
+    // Pre-check via absolute bounds. |value| > Max / |factor|  => overflow.
+    // (Also catches the value==Min && factor==-1 case since |Min| > Max.)
+    // absWithoutUB: -(kMin) is UB, so compute |kMin| as -(kMin+1) + (-1) = kMax... no,
+    // |kMin| is kMax+1 which is NOT representable. The check absValue > kMax/absFactor
+    // still fires for value==kMin because absValue (computed without UB) exceeds any
+    // representable positive value when factor==-1. We compute |x| without UB below.
+    const T absValue = (value_ < 0) ? static_cast<T>(-(value_ + 1)) + (-1) : value_;
+    const T absFactor = (factor < 0) ? static_cast<T>(-(factor + 1)) + (-1) : factor;
+    if (absValue > kMax / absFactor) {
+      fault_ = true;
+      return *this;
+    }
+    value_ = static_cast<T>(value_ * factor);
+    return *this;
+  }
+
+  // Named divide (not div) to avoid the cuttlefish reserved-name escaper
+  // renaming .div( to .div_( because div() is a C stdlib (<cstdlib>) name.
+  SafeInt<T>& divide(T d) noexcept {
+    if (fault_) { return *this; }
+    if (d == 0) { fault_ = true; return *this; }
+    // INT_MIN / -1 overflows.
+    if (value_ == kMin && d == static_cast<T>(-1)) { fault_ = true; return *this; }
+    value_ = static_cast<T>(value_ / d);
+    return *this;
+  }
+
+  SafeInt<T>& mod(T d) noexcept {
+    if (fault_) { return *this; }
+    if (d == 0) { fault_ = true; return *this; }
+    if (value_ == kMin && d == static_cast<T>(-1)) { value_ = 0; return *this; }
+    value_ = static_cast<T>(value_ % d);
+    return *this;
+  }
+
+  SafeInt<T>& negate() noexcept {
+    if (fault_) { return *this; }
+    if (value_ == kMin) { fault_ = true; return *this; }
+    value_ = static_cast<T>(-value_);
+    return *this;
+  }
+
+  // Named absValue (not abs) to avoid colliding with Arduino's abs() macro
+  // (Arduino.h #defines abs(x)), which would mangle the method declaration on
+  // AVR. Same caution for any future method whose name matches an Arduino core
+  // macro (min/max/round/...).
+  SafeInt<T>& absValue() noexcept {
+    if (fault_) { return *this; }
+    if (value_ == kMin) { fault_ = true; return *this; }
+    if (value_ < 0) { value_ = static_cast<T>(-value_); }
+    return *this;
+  }
+
+  [[nodiscard]] constexpr T get() const noexcept { return value_; }
+  [[nodiscard]] bool hasFault() const noexcept { return fault_; }
+  [[nodiscard]] bool valid() const noexcept { return !fault_; }
+
+  void reset(T newValue) noexcept { value_ = newValue; fault_ = false; }
+};
+
+#endif // __TC_SAFE_INT_DEFINED
+`.trim()],
+        shimMacros: [],
+        dependencies: [],
+    };
+}

package/dist/safety/runtime/safe-traits.d.ts

@@ -0,0 +1,4 @@
+/** Returns the C++ source for the __tc_safe_traits block. Idempotent via the
+ *  __TC_SAFE_TRAITS_DEFINED guard, so emitting it from both the SafeInt and
+ *  SafeVariable polyfills is harmless (the second include is a no-op). */
+export declare function emitSafeTraits(): string;

package/dist/safety/runtime/safe-traits.js

@@ -0,0 +1,95 @@
+// Hand-rolled C++ type traits for the safety polyfills.
+//
+// AVR's avr-gcc ships neither <type_traits> nor <limits>. The SafeInt and
+// SafeVariable polyfills need is_integral / is_signed / is_same for their
+// static_asserts, but must not include <type_traits>. This helper returns a
+// self-contained C++14 block (no includes) that defines a __tc_safe_traits
+// namespace with exactly the traits the polyfills use.
+//
+// SPECIALIZATION DISCIPLINE (avoids redefinition errors):
+// On AVR, the fixed-width typedefs alias the built-ins: int8_t == signed char,
+// int16_t == short, int32_t == long (int is 16-bit on AVR). Specializing for
+// BOTH a typedef and its underlying built-in is a redefinition error. So:
+//   - is_integral / is_signed specialize the BUILT-IN types only (signed char,
+//     short, int, long, long long, unsigned variants, char, bool). A lookup
+//     via a typedef (is_integral<int32_t>) resolves to the built-in
+//     specialization automatically because the typedef names the same type.
+//   - bounds specializes the FIXED-WIDTH typedefs only (int8_t/int16_t/
+//     int32_t/int64_t). Each typedef maps to exactly one specialization, and
+//     the bounds values match the typedef's width (not the host 'int' width).
+/** Returns the C++ source for the __tc_safe_traits block. Idempotent via the
+ *  __TC_SAFE_TRAITS_DEFINED guard, so emitting it from both the SafeInt and
+ *  SafeVariable polyfills is harmless (the second include is a no-op). */
+export function emitSafeTraits() {
+    return `
+#ifndef __TC_SAFE_TRAITS_DEFINED
+#define __TC_SAFE_TRAITS_DEFINED
+
+// No #include here: the integer types come transitively from <Arduino.h> on
+// embedded targets (which pulls <stdint.h>) and from the test harness's own
+// includes on native. This mirrors the other safety polyfills (mode-table,
+// vote) which use uint32_t with no explicit include.
+
+namespace __tc_safe_traits {
+
+// is_integral<T>: specialized on canonical built-in integer types only.
+// Lookups via fixed-width typedefs (int8_t/int32_t/etc.) resolve to these
+// because each typedef names the same type as its underlying built-in.
+template <typename T> struct is_integral { static constexpr bool value = false; };
+template <> struct is_integral<bool>               { static constexpr bool value = true; };
+template <> struct is_integral<char>               { static constexpr bool value = true; };
+template <> struct is_integral<signed char>        { static constexpr bool value = true; };
+template <> struct is_integral<unsigned char>      { static constexpr bool value = true; };
+template <> struct is_integral<short>              { static constexpr bool value = true; };
+template <> struct is_integral<unsigned short>     { static constexpr bool value = true; };
+template <> struct is_integral<int>                { static constexpr bool value = true; };
+template <> struct is_integral<unsigned int>       { static constexpr bool value = true; };
+template <> struct is_integral<long>               { static constexpr bool value = true; };
+template <> struct is_integral<unsigned long>      { static constexpr bool value = true; };
+template <> struct is_integral<long long>          { static constexpr bool value = true; };
+template <> struct is_integral<unsigned long long> { static constexpr bool value = true; };
+
+// is_signed<T>: specialized on canonical signed built-in integer types only.
+template <typename T> struct is_signed { static constexpr bool value = false; };
+template <> struct is_signed<signed char> { static constexpr bool value = true; };
+template <> struct is_signed<short>       { static constexpr bool value = true; };
+template <> struct is_signed<int>         { static constexpr bool value = true; };
+template <> struct is_signed<long>        { static constexpr bool value = true; };
+template <> struct is_signed<long long>   { static constexpr bool value = true; };
+
+// is_same<T,U>: standard two-type trait.
+template <typename T, typename U> struct is_same { static constexpr bool value = false; };
+template <typename T> struct is_same<T, T> { static constexpr bool value = true; };
+
+// bounds<T>: per-fixed-width min/max via literals + static_cast (no <limits>).
+// Specialized on the FIXED-WIDTH typedefs only. Each typedef has a unique
+// specialization whose bounds match that typedef's width (independent of the
+// host 'int' width — critical because AVR's int is 16-bit while ESP32/native
+// is 32-bit). int64_t is guarded because some freestanding toolchains lack it.
+template <typename T> struct bounds;
+template <> struct bounds<int8_t> {
+  static constexpr int8_t kMin = static_cast<int8_t>(static_cast<uint8_t>(0x80u));
+  static constexpr int8_t kMax = static_cast<int8_t>(0x7Fu);
+};
+template <> struct bounds<int16_t> {
+  static constexpr int16_t kMin = static_cast<int16_t>(static_cast<uint16_t>(0x8000u));
+  static constexpr int16_t kMax = static_cast<int16_t>(0x7FFFu);
+};
+template <> struct bounds<int32_t> {
+  static constexpr int32_t kMin = static_cast<int32_t>(static_cast<uint32_t>(0x80000000u));
+  static constexpr int32_t kMax = static_cast<int32_t>(0x7FFFFFFFu);
+};
+#if defined(__INT64_TYPE__)
+template <> struct bounds<__INT64_TYPE__> {
+  // Use unsigned-long-long literals (standard 'ull' suffix) and cast — the
+  // 'ill' signed suffix is a GNU extension needing -fext-numeric-literals.
+  static constexpr __INT64_TYPE__ kMin = static_cast<__INT64_TYPE__>(static_cast<unsigned long long>(0x8000000000000000ull));
+  static constexpr __INT64_TYPE__ kMax = static_cast<__INT64_TYPE__>(static_cast<unsigned long long>(0x7FFFFFFFFFFFFFFFull));
+};
+#endif
+
+}  // namespace __tc_safe_traits
+
+#endif // __TC_SAFE_TRAITS_DEFINED
+`.trim();
+}

package/dist/safety/runtime/safe-variable.d.ts

@@ -0,0 +1,39 @@
+import type { RuntimePolyfillIR } from "../../api/index.js";
+/** SafeVariable polyfill: 3-replica TMR with per-replica inversion for
+ *  integral types, and plain 3-copy TMR for float/double.
+ *
+ *  Combines TMR (triple modular redundancy) with inverted-redundancy for
+ *  integral types: three replicas of the value, each stored alongside its
+ *  bitwise inverse. On read, each replica is individually validated (XOR
+ *  check), then the valid replicas are majority-voted. This gives both
+ *  detection AND correction:
+ *
+ *  - A single-bit SEU in any replica's value or inverse breaks that
+ *    replica's XOR invariant → the corrupted replica is excluded from
+ *    the vote, and the good replicas correct it.
+ *  - If two replicas agree (majority), the value is returned with
+ *    confidence. The corrupted replica is silently repaired on the next
+ *    set().
+ *  - For float/double, replicas are stored as plain copies (no inversion
+ *    possible), and majority vote still corrects single-replica corruption.
+ *
+ *  Fault signaling: hasFault() returns true iff the last get() found ZERO
+ *  valid replicas (triple corruption). Callers should check hasFault() after
+ *  get() on safety-critical paths. set() clears the fault flag.
+ *
+ *  Memory cost: 3× T (same as plain TMR). The inversion is per-replica and
+ *  does not add copies beyond the three TMR replicas.
+ *
+ *  Arithmetic T only — a static_assert rejects non-arithmetic types (notably
+ *  std::string) and bool (for which bitwise inversion is ill-defined) at
+ *  compile time. float and double have explicit specializations.
+ *
+ *  AUTOSAR C++14 compliance:
+ *  - noexcept on all methods (A15-0-2)
+ *  - [[nodiscard]] on get/valid/hasFault (A0-1-1)
+ *  - constexpr constructors/methods
+ *  - no malloc/new (A18-5-8/A18-5-10)
+ *  - no C-style casts (M5-0-7)
+ *  - fixed-width types via template parameter (A3-9-1)
+ */
+export declare function safeVariablePolyfill(): RuntimePolyfillIR;

package/dist/safety/runtime/safe-variable.js

@@ -0,0 +1,226 @@
+import { emitSafeTraits } from "./safe-traits.js";
+/** SafeVariable polyfill: 3-replica TMR with per-replica inversion for
+ *  integral types, and plain 3-copy TMR for float/double.
+ *
+ *  Combines TMR (triple modular redundancy) with inverted-redundancy for
+ *  integral types: three replicas of the value, each stored alongside its
+ *  bitwise inverse. On read, each replica is individually validated (XOR
+ *  check), then the valid replicas are majority-voted. This gives both
+ *  detection AND correction:
+ *
+ *  - A single-bit SEU in any replica's value or inverse breaks that
+ *    replica's XOR invariant → the corrupted replica is excluded from
+ *    the vote, and the good replicas correct it.
+ *  - If two replicas agree (majority), the value is returned with
+ *    confidence. The corrupted replica is silently repaired on the next
+ *    set().
+ *  - For float/double, replicas are stored as plain copies (no inversion
+ *    possible), and majority vote still corrects single-replica corruption.
+ *
+ *  Fault signaling: hasFault() returns true iff the last get() found ZERO
+ *  valid replicas (triple corruption). Callers should check hasFault() after
+ *  get() on safety-critical paths. set() clears the fault flag.
+ *
+ *  Memory cost: 3× T (same as plain TMR). The inversion is per-replica and
+ *  does not add copies beyond the three TMR replicas.
+ *
+ *  Arithmetic T only — a static_assert rejects non-arithmetic types (notably
+ *  std::string) and bool (for which bitwise inversion is ill-defined) at
+ *  compile time. float and double have explicit specializations.
+ *
+ *  AUTOSAR C++14 compliance:
+ *  - noexcept on all methods (A15-0-2)
+ *  - [[nodiscard]] on get/valid/hasFault (A0-1-1)
+ *  - constexpr constructors/methods
+ *  - no malloc/new (A18-5-8/A18-5-10)
+ *  - no C-style casts (M5-0-7)
+ *  - fixed-width types via template parameter (A3-9-1)
+ */
+export function safeVariablePolyfill() {
+    return {
+        kind: "polyfill",
+        id: "safety_safe_variable",
+        domain: "embedded",
+        requiredIncludes: [],
+        forwardDeclarations: [],
+        helperStructs: [],
+        helperFunctions: [`
+${emitSafeTraits()}
+
+#ifndef __TC_SAFE_VARIABLE_DEFINED
+#define __TC_SAFE_VARIABLE_DEFINED
+
+// ── SafeVariable: integer types (bitwise XOR validation per replica) ──
+// Each replica stores value + ~value. On read, each replica is validated
+// independently. Valid replicas are majority-voted; the corrupted one
+// (if any) is excluded. This provides both detection AND correction.
+template <typename T>
+struct SafeVariable {
+  // Arithmetic T only. bool is rejected explicitly because ~bool and ^bool
+  // undergo integer promotion and do not behave as a 1-bit inversion.
+  // float/double are handled by the explicit specializations below.
+  static_assert(__tc_safe_traits::is_integral<T>::value && !__tc_safe_traits::is_same<T, bool>::value,
+                "SafeVariable<T> requires an integral T (use float/double specializations for those; "
+                "std::string and bool are not supported)");
+
+private:
+  T replicaA_val;
+  T replicaA_inv;
+  T replicaB_val;
+  T replicaB_inv;
+  T replicaC_val;
+  T replicaC_inv;
+  // mutable: get() is logically const (it does not change the stored value)
+  // but caches the "last read saw triple corruption" fault flag so callers
+  // can inspect it via hasFault() after get().
+  mutable bool fault_;
+  template <typename U> friend struct SafeVariable;
+
+  static bool replicaValid(T val, T inv) noexcept {
+    return (val ^ inv) == static_cast<T>(~static_cast<T>(0));
+  }
+
+public:
+  SafeVariable() noexcept
+      : replicaA_val(0), replicaA_inv(static_cast<T>(~static_cast<T>(0))),
+        replicaB_val(0), replicaB_inv(static_cast<T>(~static_cast<T>(0))),
+        replicaC_val(0), replicaC_inv(static_cast<T>(~static_cast<T>(0))),
+        fault_(false) {}
+
+  SafeVariable(T initial) noexcept
+      : replicaA_val(initial), replicaA_inv(static_cast<T>(~initial)),
+        replicaB_val(initial), replicaB_inv(static_cast<T>(~initial)),
+        replicaC_val(initial), replicaC_inv(static_cast<T>(~initial)),
+        fault_(false) {}
+
+  template <typename U>
+  SafeVariable(const SafeVariable<U>& other) noexcept
+      : replicaA_val(static_cast<T>(other.replicaA_val)), replicaA_inv(static_cast<T>(other.replicaA_inv)),
+        replicaB_val(static_cast<T>(other.replicaB_val)), replicaB_inv(static_cast<T>(other.replicaB_inv)),
+        replicaC_val(static_cast<T>(other.replicaC_val)), replicaC_inv(static_cast<T>(other.replicaC_inv)),
+        fault_(other.fault_) {}
+
+  // Majority vote: returns the agreed-upon value from valid replicas.
+  // If a replica is corrupted (XOR check fails), it is excluded from
+  // the vote. If two or more valid replicas agree, return that value.
+  // If only one replica is valid, return it as a best-effort fallback.
+  // If NO replica is valid (triple corruption), returns replicaC_val as a
+  // last resort and sets the fault flag — callers must check hasFault().
+  [[nodiscard]] T get() const noexcept {
+    const bool aValid = replicaValid(replicaA_val, replicaA_inv);
+    const bool bValid = replicaValid(replicaB_val, replicaB_inv);
+    const bool cValid = replicaValid(replicaC_val, replicaC_inv);
+
+    // Two valid replicas agree → majority.
+    if (aValid && bValid && (replicaA_val == replicaB_val)) { fault_ = false; return replicaA_val; }
+    if (aValid && cValid && (replicaA_val == replicaC_val)) { fault_ = false; return replicaA_val; }
+    if (bValid && cValid && (replicaB_val == replicaC_val)) { fault_ = false; return replicaB_val; }
+
+    // Only one valid replica → return it (no majority but best available).
+    if (aValid) { fault_ = false; return replicaA_val; }
+    if (bValid) { fault_ = false; return replicaB_val; }
+    if (cValid) { fault_ = false; return replicaC_val; }
+
+    // Zero valid replicas → triple corruption. Flag the fault and return
+    // replicaC_val as a degenerate fallback; callers MUST check hasFault().
+    fault_ = true;
+    return replicaC_val;
+  }
+
+  // Returns true if all three replicas pass their XOR checks AND agree.
+  // Does not mutate the fault flag (it reflects the last get(), not valid()).
+  [[nodiscard]] bool valid() const noexcept {
+    return replicaValid(replicaA_val, replicaA_inv)
+        && replicaValid(replicaB_val, replicaB_inv)
+        && replicaValid(replicaC_val, replicaC_inv)
+        && (replicaA_val == replicaB_val)
+        && (replicaB_val == replicaC_val);
+  }
+
+  // Returns true iff the most recent get() found zero valid replicas
+  // (triple corruption). Cleared by set() and by a subsequent get() that
+  // finds at least one valid replica.
+  [[nodiscard]] bool hasFault() const noexcept { return fault_; }
+
+  void set(T newValue) noexcept {
+    const T inv = static_cast<T>(~newValue);
+    replicaA_val = newValue; replicaA_inv = inv;
+    replicaB_val = newValue; replicaB_inv = inv;
+    replicaC_val = newValue; replicaC_inv = inv;
+    fault_ = false;
+  }
+};
+
+// ── SafeVariable: float (3-replica majority vote, no inversion) ──
+// Floats can't use bitwise XOR/inversion. Three identical copies are
+// stored and majority-voted. A single corrupted copy is outvoted and
+// silently repaired on the next set().
+template <>
+struct SafeVariable<float> {
+private:
+  float replicaA;
+  float replicaB;
+  float replicaC;
+  mutable bool fault_;
+  template <typename U> friend struct SafeVariable;
+public:
+  SafeVariable() noexcept : replicaA(0.0f), replicaB(0.0f), replicaC(0.0f), fault_(false) {}
+  SafeVariable(float initial) noexcept : replicaA(initial), replicaB(initial), replicaC(initial), fault_(false) {}
+  [[nodiscard]] float get() const noexcept {
+    if (replicaA == replicaB) { fault_ = false; return replicaA; }
+    if (replicaA == replicaC) { fault_ = false; return replicaA; }
+    if (replicaB == replicaC) { fault_ = false; return replicaB; }
+    // No two replicas agree — triple corruption.
+    fault_ = true;
+    return replicaC;
+  }
+  [[nodiscard]] bool valid() const noexcept {
+    return (replicaA == replicaB) && (replicaB == replicaC);
+  }
+  [[nodiscard]] bool hasFault() const noexcept { return fault_; }
+  void set(float newValue) noexcept {
+    replicaA = newValue;
+    replicaB = newValue;
+    replicaC = newValue;
+    fault_ = false;
+  }
+};
+
+// ── SafeVariable: double (3-replica majority vote, no inversion) ──
+template <>
+struct SafeVariable<double> {
+private:
+  double replicaA;
+  double replicaB;
+  double replicaC;
+  mutable bool fault_;
+  template <typename U> friend struct SafeVariable;
+public:
+  SafeVariable() noexcept : replicaA(0.0), replicaB(0.0), replicaC(0.0), fault_(false) {}
+  SafeVariable(double initial) noexcept : replicaA(initial), replicaB(initial), replicaC(initial), fault_(false) {}
+  [[nodiscard]] double get() const noexcept {
+    if (replicaA == replicaB) { fault_ = false; return replicaA; }
+    if (replicaA == replicaC) { fault_ = false; return replicaA; }
+    if (replicaB == replicaC) { fault_ = false; return replicaB; }
+    // No two replicas agree — triple corruption.
+    fault_ = true;
+    return replicaC;
+  }
+  [[nodiscard]] bool valid() const noexcept {
+    return (replicaA == replicaB) && (replicaB == replicaC);
+  }
+  [[nodiscard]] bool hasFault() const noexcept { return fault_; }
+  void set(double newValue) noexcept {
+    replicaA = newValue;
+    replicaB = newValue;
+    replicaC = newValue;
+    fault_ = false;
+  }
+};
+
+#endif // __TC_SAFE_VARIABLE_DEFINED
+`.trim()],
+        shimMacros: [],
+        dependencies: [],
+    };
+}

package/dist/safety/runtime/vote.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimePolyfillIR } from "../../api/index.js";
+/** The 2-of-3 voter. Tree-shaken out unless __tc_safety_read_safe appears
+ *  in the program (registered in POLYFILL_HELPER_MAP).
+ *
+ *  MCU-agnosticism: the voter reads via the strategy-injected __tc_gpio_read
+ *  shim (defined per-target by each framework strategy's shimLines()). The
+ *  safety package references zero target-specific symbols. */
+export declare function voterPolyfill(): RuntimePolyfillIR;

package/dist/safety/runtime/vote.js

@@ -0,0 +1,92 @@
+/** The 2-of-3 voter. Tree-shaken out unless __tc_safety_read_safe appears
+ *  in the program (registered in POLYFILL_HELPER_MAP).
+ *
+ *  MCU-agnosticism: the voter reads via the strategy-injected __tc_gpio_read
+ *  shim (defined per-target by each framework strategy's shimLines()). The
+ *  safety package references zero target-specific symbols. */
+export function voterPolyfill() {
+    return {
+        kind: "polyfill",
+        id: "safety_read_safe",
+        domain: "embedded",
+        requiredIncludes: [],
+        forwardDeclarations: [],
+        helperStructs: [],
+        helperFunctions: [`
+// Forward declarations — the strategy's shimLines() defines these AFTER the
+// polyfill block (polyfills emit before shims in emitPreamble). Without the
+// forward decls, the voter's __tc_gpio_read / __tc_delay_us calls below would
+// be unresolved.
+int __tc_gpio_read(uint32_t pin);
+void __tc_delay_us(uint32_t us);
+
+namespace __tc_safety {
+
+// Settle delay between temporally-separated reads. ~2 us is enough to defeat
+// single-event transient (SET) glitches on a typical GPIO line while staying
+// well under a debounce timescale. Tunable in one place.
+constexpr uint32_t TC_SAFETY_SETTLE_US = 2U;
+
+// Perform 3 temporally-separated reads via the strategy-injected shim, take
+// the majority. On disagreement, VoteDisagreement. On pin-mode mismatch,
+// PinModeMismatch. On untracked pin, PinModeUnknown. value is left 0 when
+// ok==false — callers must check 'ok' before consuming 'value'.
+inline SafeReadResult read_safe(uint32_t pin) {
+  SafeReadResult result;
+  result.value    = 0x00000000U;
+  result.category = SafetyFaultCategory::Ok;
+  result.code     = SafetyFaultCode::Ok;
+  result.status   = SafetyStatus::Ok;
+
+  // 1. Confirm pin mode (Input, InputPullup, or InputPulldown are valid for
+  // reading). Output is rejected (PinModeMismatch). InputPulldown is
+  // accepted because it is a legitimate input mode on ESP32 (and AVR via
+  // external pulldown); rejecting it caused false faults.
+  const TrackedMode mode = get_pin_mode(pin);
+  if (mode == TrackedMode::Unknown) {
+    result.category = SafetyFaultCategory::Configuration;
+    result.code     = SafetyFaultCode::PinModeUnknown;
+    result.status   = SafetyStatus::Fault;
+    return result;
+  }
+  if ((mode != TrackedMode::Input) && (mode != TrackedMode::InputPullup) && (mode != TrackedMode::InputPulldown)) {
+    result.category = SafetyFaultCategory::Configuration;
+    result.code     = SafetyFaultCode::PinModeMismatch;
+    result.status   = SafetyStatus::Fault;
+    return result;
+  }
+
+  // 2. 2-of-3 vote via the strategy-injected __tc_gpio_read shim.
+  // __tc_delay_us provides temporal separation between reads so a single
+  // input glitch is unlikely to corrupt two samples; the strategy injects a
+  // real microsecond delay (Arduino/ESP32: delayMicroseconds; AVR:
+  // _native_delay_us; native: stub).
+  const uint32_t r0 = __tc_gpio_read(pin);
+  __tc_delay_us(TC_SAFETY_SETTLE_US);
+  const uint32_t r1 = __tc_gpio_read(pin);
+  __tc_delay_us(TC_SAFETY_SETTLE_US);
+  const uint32_t r2 = __tc_gpio_read(pin);
+
+  if ((r0 == r1) && (r1 == r2)) {
+    result.status = SafetyStatus::Ok;
+    result.value  = r0 ? 0xFFFFFFFFU : 0x00000000U;
+  } else {
+    result.category = SafetyFaultCategory::Signal;
+    result.code     = SafetyFaultCode::VoteDisagreement;
+    result.status   = SafetyStatus::Fault;
+  }
+  return result;
+}
+
+// Namespace-scoped forwarding entry point — kept inside the namespace so
+// the emitter's forward-declaration pass does not generate a global prototype
+// that references SafeReadResult before the struct is defined.
+inline SafeReadResult __tc_safety_read_safe(uint32_t pin) {
+  return read_safe(pin);
+}
+
+}  // namespace __tc_safety`.trim()],
+        shimMacros: [],
+        dependencies: ["safety_mode_table"],
+    };
+}