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

package/dist/safety/iso26262/init-checker.js

@@ -0,0 +1,127 @@
+import { asilLevel, ASIL_THRESHOLDS } from "./asil.js";
+/** B5: Init completeness (ISO 26262 Part 6, §7.4.5 — ASIL D).
+ *
+ *  Checks that every identifier used in a safety-critical function (ASIL D)
+ *  was initialized in setup() or at file scope. An uninitialized variable
+ *  in a safety-critical path is a potential source of undefined behavior.
+ *
+ *  Approach: collect identifiers assigned/declared in setup() and top-level
+ *  (the "init set"), then walk each ASIL D function's statements looking
+ *  for identifiers used before any local assignment. Reports each as a
+ *  warning. */
+export function checkInitCompleteness(program, _ctx) {
+    const diags = [];
+    // Collect the "init set": identifiers declared/assigned in setup() and
+    // top-level statements. These are considered initialized.
+    const initSet = new Set();
+    // Top-level var_decls and assignments
+    for (const stmt of program.topLevelStatements) {
+        collectAssignedNames(stmt, initSet);
+    }
+    // setup() statements
+    const setupFn = program.functions.find(fn => fn.originalName === "setup");
+    if (setupFn) {
+        for (const stmt of setupFn.statements) {
+            collectAssignedNames(stmt, initSet);
+        }
+    }
+    // Check each ASIL D function for use of identifiers not in the init set
+    for (const fn of program.functions) {
+        if (fn.originalName === "setup" || fn.originalName === "loop")
+            continue;
+        if (asilLevel(fn.decorators) < ASIL_THRESHOLDS.dynamicAlloc)
+            continue;
+        // Collect locally-declared names in this function (params + local vars)
+        const localNames = new Set();
+        for (const param of fn.parameters) {
+            localNames.add(param.name);
+        }
+        // Walk statements — look for identifiers used before local declaration
+        for (const stmt of fn.statements) {
+            checkUsedBeforeDeclared(stmt, fn.originalName, initSet, localNames, diags);
+        }
+    }
+    return diags;
+}
+/** Collect names that are declared or assigned in a statement tree. */
+function collectAssignedNames(stmt, names) {
+    if (!stmt || typeof stmt !== "object")
+        return;
+    if (stmt.kind === "var_decl" && typeof stmt.name === "string") {
+        names.add(stmt.name);
+    }
+    if (stmt.kind === "assign" && typeof stmt.target === "string") {
+        names.add(stmt.target);
+    }
+    if (stmt.kind === "update" && typeof stmt.target === "string") {
+        names.add(stmt.target);
+    }
+    for (const key of Object.keys(stmt)) {
+        const val = stmt[key];
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                if (item && typeof item === "object" && typeof item.kind === "string") {
+                    collectAssignedNames(item, names);
+                }
+            }
+        }
+        else if (val && typeof val === "object" && typeof val.kind === "string") {
+            collectAssignedNames(val, names);
+        }
+    }
+}
+/** Check if a statement uses identifiers that were never initialized. */
+function checkUsedBeforeDeclared(stmt, fnName, initSet, localNames, diags) {
+    if (!stmt || typeof stmt !== "object")
+        return;
+    // Check identifiers used in expressions
+    if (stmt.kind === "identifier" && typeof stmt.value === "string") {
+        const name = stmt.value;
+        // Skip if it's initialized at file scope/setup, or declared locally,
+        // or it's a known built-in (skip common names).
+        if (!initSet.has(name) && !localNames.has(name) && !isBuiltin(name)) {
+            diags.push({
+                severity: "warning",
+                code: "ISO26262_B5_INIT_COMPLETENESS",
+                message: `Variable '${name}' used in ${fnName}() may not be initialized in setup() or at file scope`,
+                hint: "ASIL D requires all variables in safety-critical paths to be initialized before use. Initialize in setup() or declare at file scope.",
+            });
+        }
+    }
+    // Recurse
+    for (const key of Object.keys(stmt)) {
+        const val = stmt[key];
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                if (item && typeof item === "object" && typeof item.kind === "string") {
+                    checkUsedBeforeDeclared(item, fnName, initSet, localNames, diags);
+                }
+            }
+        }
+        else if (val && typeof val === "object" && typeof val.kind === "string") {
+            checkUsedBeforeDeclared(val, fnName, initSet, localNames, diags);
+        }
+    }
+}
+function isBuiltin(name) {
+    // Common names that don't need explicit init
+    const builtins = new Set([
+        "true", "false", "null", "undefined", "undefined_t",
+        "console", "Math", "Timing", "Serial", "WDT", "Preferences",
+        "delay", "millis", "micros", "delayMicroseconds",
+        "HIGH", "LOW", "INPUT", "OUTPUT", "INPUT_PULLUP", "INPUT_PULLDOWN",
+        "LED_BUILTIN", "Serial",
+        // Cuttlefish internal names
+        "__tc_", "SafeReadResult", "SafeWriteResult", "SafeVariable", "SafeInt",
+        "safe", "volatile",
+    ]);
+    if (builtins.has(name))
+        return true;
+    // Skip names starting with __ (cuttlefish internal)
+    if (name.startsWith("__"))
+        return true;
+    // Skip all-caps names (likely macros/constants)
+    if (name === name.toUpperCase() && name.length > 1)
+        return true;
+    return false;
+}

package/dist/safety/iso26262/loop-checker.d.ts

@@ -0,0 +1,7 @@
+import type { ProgramIR, Diagnostic } from "../../api/index.js";
+import type { SafetyTransformContext } from "../../safety-hook.js";
+/** B3: Unbounded loop detection (ISO 26262 Part 6, §7.4.10 — ASIL C+).
+ *
+ *  Only checks functions decorated with @asilC or higher.
+ *  Lower ASIL levels and QM functions are skipped. */
+export declare function checkUnboundedLoops(program: ProgramIR, _ctx: SafetyTransformContext): Diagnostic[];

package/dist/safety/iso26262/loop-checker.js

@@ -0,0 +1,86 @@
+import { asilLevel, ASIL_THRESHOLDS } from "./asil.js";
+/** B3: Unbounded loop detection (ISO 26262 Part 6, §7.4.10 — ASIL C+).
+ *
+ *  Only checks functions decorated with @asilC or higher.
+ *  Lower ASIL levels and QM functions are skipped. */
+export function checkUnboundedLoops(program, _ctx) {
+    const diags = [];
+    for (const fn of program.functions) {
+        if (asilLevel(fn.decorators) < ASIL_THRESHOLDS.unboundedLoop)
+            continue;
+        for (const stmt of fn.statements) {
+            scanForUnboundedLoop(stmt, fn.originalName, diags);
+        }
+    }
+    for (const cls of program.classes) {
+        for (const method of cls.methods) {
+            if (!method.name)
+                continue;
+            if (asilLevel(method.decorators) < ASIL_THRESHOLDS.unboundedLoop)
+                continue;
+            for (const stmt of method.statements) {
+                scanForUnboundedLoop(stmt, method.name, diags);
+            }
+        }
+    }
+    return diags;
+}
+function scanForUnboundedLoop(stmt, fnName, diags) {
+    if (!stmt || typeof stmt !== "object")
+        return;
+    if (stmt.kind === "while") {
+        const cond = stmt.condition;
+        if (isConstantTrue(cond)) {
+            diags.push({
+                severity: "warning",
+                code: "ISO26262_B3_UNBOUNDED_LOOP",
+                message: `Unbounded while(true) in ${fnName}()`,
+                hint: "Use a bounded loop counter or a timeout guard to ensure termination.",
+            });
+        }
+    }
+    if (stmt.kind === "for" && !stmt.condition) {
+        diags.push({
+            severity: "warning",
+            code: "ISO26262_B3_UNBOUNDED_LOOP",
+            message: `Unbounded for(;;) in ${fnName}()`,
+            hint: "Use a bounded loop counter or a timeout guard to ensure termination.",
+        });
+    }
+    if (stmt.kind === "do_while") {
+        const cond = stmt.condition;
+        if (isConstantTrue(cond)) {
+            diags.push({
+                severity: "warning",
+                code: "ISO26262_B3_UNBOUNDED_LOOP",
+                message: `Unbounded do-while(true) in ${fnName}()`,
+                hint: "Use a bounded loop counter or a timeout guard to ensure termination.",
+            });
+        }
+    }
+    for (const key of Object.keys(stmt)) {
+        const val = stmt[key];
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                if (item && typeof item === "object" && typeof item.kind === "string") {
+                    scanForUnboundedLoop(item, fnName, diags);
+                }
+            }
+        }
+        else if (val && typeof val === "object" && typeof val.kind === "string") {
+            scanForUnboundedLoop(val, fnName, diags);
+        }
+    }
+}
+function isConstantTrue(expr) {
+    if (!expr)
+        return false;
+    if (expr.kind === "raw" && typeof expr.value === "string") {
+        return /^(true|1)$/.test(expr.value.trim());
+    }
+    if (expr.kind === "boolean" && expr.value === true)
+        return true;
+    if (expr.kind === "number" && expr.value !== 0)
+        return true;
+    return false;
+}

package/dist/safety/iso26262/recursion-checker.d.ts

@@ -0,0 +1,9 @@
+import type { ProgramIR, Diagnostic } from "../../api/index.js";
+import type { SafetyTransformContext } from "../../safety-hook.js";
+/** B1: No recursion (ISO 26262 Part 6, Table 8 — ASIL B+).
+ *
+ *  Only checks functions decorated with @asilB or higher.
+ *  QM/ASIL A functions are skipped.
+ *
+ *  Builds a function call graph and runs DFS cycle detection. */
+export declare function checkRecursion(program: ProgramIR, _ctx: SafetyTransformContext): Diagnostic[];

package/dist/safety/iso26262/recursion-checker.js

@@ -0,0 +1,134 @@
+import { asilLevel, ASIL_THRESHOLDS } from "./asil.js";
+/** B1: No recursion (ISO 26262 Part 6, Table 8 — ASIL B+).
+ *
+ *  Only checks functions decorated with @asilB or higher.
+ *  QM/ASIL A functions are skipped.
+ *
+ *  Builds a function call graph and runs DFS cycle detection. */
+export function checkRecursion(program, _ctx) {
+    const diags = [];
+    // Build function set (only ASIL-annotated functions are checked)
+    const asilFnNames = new Set();
+    for (const fn of program.functions) {
+        if (asilLevel(fn.decorators) >= ASIL_THRESHOLDS.recursion) {
+            asilFnNames.add(fn.originalName);
+        }
+    }
+    for (const cls of program.classes) {
+        for (const method of cls.methods) {
+            if (method.name && asilLevel(method.decorators) >= ASIL_THRESHOLDS.recursion) {
+                asilFnNames.add(method.name);
+            }
+        }
+    }
+    if (asilFnNames.size === 0)
+        return diags;
+    // Build call graph (all functions, not just ASIL — callees matter)
+    const callGraph = buildFunctionCallGraph(program);
+    // DFS cycle detection — only report cycles involving ASIL functions
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map();
+    for (const name of callGraph.keys()) {
+        color.set(name, WHITE);
+    }
+    for (const entry of callGraph.keys()) {
+        if (color.get(entry) === WHITE) {
+            const path = [];
+            dfs(entry, callGraph, color, path, (cycle) => {
+                // Only report if any function in the cycle is ASIL-annotated
+                if (cycle.some(name => asilFnNames.has(name))) {
+                    diags.push({
+                        severity: "error",
+                        code: "ISO26262_B1_RECURSION",
+                        message: `Recursion detected: ${cycle.join(" → ")}`,
+                        hint: "ASIL B+ requires bounded call depth. Refactor to an iterative loop or use a fixed-size memoization table.",
+                    });
+                }
+            });
+        }
+    }
+    return diags;
+}
+function buildFunctionCallGraph(program) {
+    const graph = new Map();
+    const allFnNames = new Set();
+    for (const fn of program.functions) {
+        allFnNames.add(fn.originalName);
+    }
+    for (const cls of program.classes) {
+        for (const method of cls.methods) {
+            if (method.name)
+                allFnNames.add(method.name);
+        }
+    }
+    for (const fn of program.functions) {
+        const name = fn.originalName;
+        const deps = new Set();
+        for (const stmt of fn.statements) {
+            collectCallTargets(stmt, allFnNames, deps);
+        }
+        graph.set(name, deps);
+    }
+    for (const cls of program.classes) {
+        for (const method of cls.methods) {
+            if (!method.name)
+                continue;
+            const deps = new Set();
+            for (const stmt of method.statements) {
+                collectCallTargets(stmt, allFnNames, deps);
+            }
+            const existing = graph.get(method.name);
+            if (existing) {
+                for (const d of deps)
+                    existing.add(d);
+            }
+            else {
+                graph.set(method.name, deps);
+            }
+        }
+    }
+    return graph;
+}
+function collectCallTargets(stmt, allFnNames, deps) {
+    if (!stmt || typeof stmt !== "object")
+        return;
+    if (stmt.kind === "call" && typeof stmt.callee === "string" && allFnNames.has(stmt.callee)) {
+        deps.add(stmt.callee);
+    }
+    if (stmt.kind === "method-call" && typeof stmt.callee === "string" && allFnNames.has(stmt.callee)) {
+        deps.add(stmt.callee);
+    }
+    for (const key of Object.keys(stmt)) {
+        const val = stmt[key];
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                if (item && typeof item === "object" && typeof item.kind === "string") {
+                    collectCallTargets(item, allFnNames, deps);
+                }
+            }
+        }
+        else if (val && typeof val === "object" && typeof val.kind === "string") {
+            collectCallTargets(val, allFnNames, deps);
+        }
+    }
+}
+function dfs(node, graph, color, path, onCycle) {
+    color.set(node, 1); // GRAY
+    path.push(node);
+    const neighbors = graph.get(node);
+    if (neighbors) {
+        for (const next of neighbors) {
+            const nextColor = color.get(next);
+            if (nextColor === 1) {
+                const cycleStart = path.indexOf(next);
+                const cycle = path.slice(cycleStart).concat(next);
+                onCycle(cycle);
+            }
+            else if (nextColor === 0) {
+                dfs(next, graph, color, path, onCycle);
+            }
+        }
+    }
+    path.pop();
+    color.set(node, 2); // BLACK
+}

package/dist/safety/iso26262/sidecar-writer.d.ts

@@ -0,0 +1,25 @@
+import type { SafetyMetadata } from "../../safety-hook.js";
+/** Sidecar JSON schema for the safety metadata artifact. */
+export interface SafetySidecar {
+    schemaVersion: string;
+    standard: string;
+    tool: string;
+    toolVersion: string;
+    generatedAt: string;
+    safetyFunctions: Array<{
+        name: string;
+        asilLevel: string;
+        source?: {
+            tsFile: string;
+            tsLine: number;
+        };
+        mechanisms: string[];
+        rules: Record<string, "pass" | {
+            severity: string;
+            message: string;
+        }>;
+    }>;
+}
+/** Render safety metadata as a sidecar JSON string.
+ *  Pure function — does not touch the filesystem. */
+export declare function renderSafetySidecar(metadata: SafetyMetadata, toolVersion: string): string;

package/dist/safety/iso26262/sidecar-writer.js

@@ -0,0 +1,13 @@
+/** Render safety metadata as a sidecar JSON string.
+ *  Pure function — does not touch the filesystem. */
+export function renderSafetySidecar(metadata, toolVersion) {
+    const payload = {
+        schemaVersion: "1.0.0",
+        standard: "ISO 26262 Part 6",
+        tool: "cuttlefish (safety)",
+        toolVersion,
+        generatedAt: new Date().toISOString(),
+        safetyFunctions: metadata.functions,
+    };
+    return JSON.stringify(payload, null, 2);
+}

package/dist/safety/passes/pinMode-intercept.d.ts

@@ -0,0 +1,3 @@
+import type { ProgramIR } from "../../api/index.js";
+import type { SafetyTransformContext } from "../../safety-hook.js";
+export declare function pinModeInterceptPass(program: ProgramIR, ctx: SafetyTransformContext): ProgramIR;

package/dist/safety/passes/pinMode-intercept.js

@@ -0,0 +1,60 @@
+// The post-build IR transform. Walks the built ProgramIR and injects a
+// safety.record_pin_mode companion statement after every pin-configuring
+// gpio op — gpio.configure (the thin GPIO constructor / set re-configure)
+// and gpio.read_cfg (the fused guarded-configure + read). This makes the
+// runtime mode table authoritative regardless of how the user configured
+// the pin.
+//
+// v3: the thin HAL replaced gpio.set_mode's Arduino mode strings with
+// gpio.configure's flag tokens ("GPIO.OUTPUT | GPIO.PULL_UP"). The flags
+// field carries token text at IR time; configure-shaped flag sets map onto
+// the TrackedMode enum, anything else (a runtime expression, an open-drain
+// combo with no tracked equivalent) records Unknown so the voter still sees
+// a fresh table entry rather than a stale mode.
+//
+// Produces a NEW ProgramIR via mapProgramStatements; does not mutate the input.
+// See docs/superpowers/specs/2026-07-27-safety-package-part-a-design.md.
+import { mapProgramStatements } from "../../api/index.js";
+import { mapFlagTokens } from "../hal/ops.js";
+/** The gpio ops that (re)configure a pin's direction/flags. */
+const PIN_MODE_OPS = new Set(["gpio.configure", "gpio.read_cfg"]);
+export function pinModeInterceptPass(program, ctx) {
+    if (!ctx.safetyInUse)
+        return program;
+    return mapProgramStatements(program, (stmt) => {
+        const companions = collectPinModeCompanions(stmt);
+        return companions.length === 0 ? [stmt] : [stmt, ...companions];
+    });
+}
+/** If stmt is a hal-op statement carrying a pin-configuring gpio op, return a
+ *  singleton array containing the companion record_pin_mode statement;
+ *  else []. */
+function collectPinModeCompanions(stmt) {
+    if (stmt.kind !== "hal-op")
+        return [];
+    const op = stmt.operation;
+    if (typeof op.operation !== "string")
+        return [];
+    if (!PIN_MODE_OPS.has(op.operation))
+        return [];
+    // gpio.configure / gpio.read_cfg carry { pin: number; flags: string }
+    // where flags is flag-token text ("GPIO.INPUT | GPIO.PULL_UP") or an
+    // unresolved runtime expression.
+    const pinModeOp = op;
+    if (typeof pinModeOp.pin !== "number" || typeof pinModeOp.flags !== "string")
+        return [];
+    return [makeCompanion(pinModeOp.pin, mapFlagTokens(pinModeOp.flags))];
+}
+function makeCompanion(pin, mode) {
+    const companionOp = {
+        operation: "safety.record_pin_mode",
+        pin,
+        mode,
+    };
+    return {
+        kind: "hal-op",
+        operation: companionOp,
+        returns_value: false,
+        sourceSpan: { startLine: 0, startColumn: 0, filePath: "<safety-companion>" },
+    };
+}

package/dist/safety/runtime/mode-table.d.ts

@@ -0,0 +1,5 @@
+import type { RuntimePolyfillIR } from "../../api/index.js";
+/** The pin-mode tracking table + accessors. Tree-shaken out unless
+ *  __tc_safety_record_pin_mode appears in the program (registered in
+ *  POLYFILL_HELPER_MAP). */
+export declare function modeTablePolyfill(): RuntimePolyfillIR;

package/dist/safety/runtime/mode-table.js

@@ -0,0 +1,55 @@
+import { emitResultStructs } from "./result-struct.js";
+/** The pin-mode tracking table + accessors. Tree-shaken out unless
+ *  __tc_safety_record_pin_mode appears in the program (registered in
+ *  POLYFILL_HELPER_MAP). */
+export function modeTablePolyfill() {
+    return {
+        kind: "polyfill",
+        id: "safety_mode_table",
+        domain: "embedded",
+        requiredIncludes: [],
+        forwardDeclarations: [],
+        helperStructs: [],
+        helperFunctions: [
+            emitResultStructs(),
+            `
+namespace __tc_safety {
+constexpr uint32_t TC_SAFETY_PIN_TABLE_SIZE = 255U;
+
+enum class TrackedMode : uint32_t {
+  Unknown       = 0x00000000U,
+  Input         = 0x5A5A5A5AU,
+  Output        = 0xA5A5A5A5U,
+  InputPullup   = 0x3C3C3C3CU,
+  InputPulldown = 0xC3C3C3C3U,
+};
+
+// Raw array: unavoidable for O(1) pin-indexed lookup in an embedded shim.
+// Zero-initialized namespace-scope static storage (Unknown = 0U) satisfies
+// M3-2-1 (const-init) and M3-2-4 (trivial static init); no knownPatterns
+// deviation needed (verified in Part A v1).
+TrackedMode g_pin_mode_table[TC_SAFETY_PIN_TABLE_SIZE];
+
+inline void record_pin_mode(uint32_t pin, uint32_t mode) {
+  if (pin < TC_SAFETY_PIN_TABLE_SIZE) {
+    g_pin_mode_table[pin] = static_cast<TrackedMode>(mode);
+  }
+}
+
+inline TrackedMode get_pin_mode(uint32_t pin) {
+  if (pin < TC_SAFETY_PIN_TABLE_SIZE) {
+    return g_pin_mode_table[pin];
+  }
+  return TrackedMode::Unknown;
+}
+}  // namespace __tc_safety
+
+inline void __tc_safety_record_pin_mode(uint32_t pin, uint32_t mode) {
+  __tc_safety::record_pin_mode(pin, mode);
+}
+`.trim(),
+        ],
+        shimMacros: [],
+        dependencies: [],
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { RuntimePolyfillIR } from "../../api/index.js";
+/** All safety runtime polyfills, in dependency order (mode table before voter
+ *  and write-verify, safe variable and safe int are standalone). Returned by
+ *  the safety hook's buildPolyfills(); called from buildEmitterContext so each
+ *  polyfill participates in usage-based tree-shaking via filterPolyfillHelpers. */
+export declare function buildSafetyPolyfills(): RuntimePolyfillIR[];

package/dist/safety/runtime/polyfills.js

@@ -0,0 +1,12 @@
+import { modeTablePolyfill } from "./mode-table.js";
+import { voterPolyfill } from "./vote.js";
+import { safeVariablePolyfill } from "./safe-variable.js";
+import { safeIntPolyfill } from "./safe-int.js";
+import { writeVerifyPolyfill } from "./write-verify.js";
+/** All safety runtime polyfills, in dependency order (mode table before voter
+ *  and write-verify, safe variable and safe int are standalone). Returned by
+ *  the safety hook's buildPolyfills(); called from buildEmitterContext so each
+ *  polyfill participates in usage-based tree-shaking via filterPolyfillHelpers. */
+export function buildSafetyPolyfills() {
+    return [modeTablePolyfill(), voterPolyfill(), writeVerifyPolyfill(), safeVariablePolyfill(), safeIntPolyfill()];
+}

package/dist/safety/runtime/result-struct.d.ts

@@ -0,0 +1,11 @@
+/** Returns the C++ enum + struct definitions for the safety runtime.
+ *
+ *  These are emitted by the polyfill as the SINGLE canonical source.
+ *  @typecad/safety is skipped by the graph-builder (like @typecad/ui), so
+ *  its TypeScript source is never parsed into the user program's IR — the
+ *  type-decl emitter never sees the enums. The polyfill provides the
+ *  definitions that both the voter and the user's switch statements
+ *  reference. Works in both single-file and split-file emit modes because
+ *  the polyfill is inlined into the entry file's source, visible to all
+ *  functions in that translation unit. */
+export declare function emitResultStructs(): string;

package/dist/safety/runtime/result-struct.js

@@ -0,0 +1,98 @@
+// C++ source strings for the safety result struct + fault enums. Emitted by
+// the mode-table polyfill (Task 9) BEFORE the voter, so the voter can return
+// a SafeReadResult.
+//
+// AUTOSAR C++14 compliance:
+//  - enum class (A7-2-1)
+//  - fixed-width types (A3-9-1): uint8_t
+//  - no C-style casts (M5-0-7), no malloc (A18-5-10)
+//  - the raw pin table in mode-table.ts is zero-initialized namespace-scope
+//    static storage, satisfying M3-2-1/M3-2-4. No knownPatterns deviation is
+//    expected; if a rule fires anyway, add one (see
+//    docs/superpowers/plans/2026-07-27-safety-package-part-a.md Task 17).
+/** Returns the C++ enum + struct definitions for the safety runtime.
+ *
+ *  These are emitted by the polyfill as the SINGLE canonical source.
+ *  @typecad/safety is skipped by the graph-builder (like @typecad/ui), so
+ *  its TypeScript source is never parsed into the user program's IR — the
+ *  type-decl emitter never sees the enums. The polyfill provides the
+ *  definitions that both the voter and the user's switch statements
+ *  reference. Works in both single-file and split-file emit modes because
+ *  the polyfill is inlined into the entry file's source, visible to all
+ *  functions in that translation unit. */
+export function emitResultStructs() {
+    return `
+enum class SafetyStatus : uint32_t {
+  Ok    = 0x5A5A5A5AU,
+  Fault = 0xA5A5A5A5U,
+};
+
+enum class SafetyFaultCategory : uint32_t {
+  Ok            = 0x3C3C3C3CU,
+  Signal        = 0x5A5A5A5AU,
+  Integrity     = 0xA5A5A5A5U,
+  Timing        = 0xC3C3C3C3U,
+  System        = 0x55AA55AAU,
+  Configuration = 0xAA55AA55U,
+};
+
+enum class SafetyFaultCode : uint32_t {
+  Ok               = 0x3C3C3C3CU,
+  VoteDisagreement = 0x5A5A5A5AU,
+  StuckHigh        = 0xA5A5A5A5U,
+  StuckLow         = 0xC3C3C3C3U,
+  PinModeMismatch  = 0x55AA55AAU,
+  PinModeUnknown   = 0xAA55AA55U,
+  WriteMismatch    = 0x3C5AA5C3U,
+};
+
+struct SafeReadResult {
+  SafetyStatus status;
+  uint32_t value;
+  SafetyFaultCategory category;
+  SafetyFaultCode code;
+
+  // Chainable result handlers. Each calls the handler at runtime when its
+  // condition matches, then returns *this so chains compose and the result
+  // stays inspectable afterward. Template F&& accepts the inline C++ lambdas
+  // cuttlefish renders — no std::function, no heap allocation.
+  template <typename F>
+  SafeReadResult& ok(F&& handler) noexcept {
+    if (status == SafetyStatus::Ok) { handler(*this); }
+    return *this;
+  }
+  template <typename F>
+  SafeReadResult& fail(F&& handler) noexcept {
+    if (status != SafetyStatus::Ok) { handler(*this); }
+    return *this;
+  }
+  // fault is an alias of fail (no std::forward — avoids the <utility> header
+  // AVR lacks; the handler is called once immediately, so perfect forwarding
+  // is not load-bearing).
+  template <typename F>
+  SafeReadResult& fault(F&& handler) noexcept { return fail(handler); }
+  template <typename F>
+  SafeReadResult& always(F&& handler) noexcept { handler(*this); return *this; }
+};
+
+struct SafeWriteResult {
+  SafetyStatus status;
+  SafetyFaultCode code;
+
+  template <typename F>
+  SafeWriteResult& ok(F&& handler) noexcept {
+    if (status == SafetyStatus::Ok) { handler(*this); }
+    return *this;
+  }
+  template <typename F>
+  SafeWriteResult& fail(F&& handler) noexcept {
+    if (status != SafetyStatus::Ok) { handler(*this); }
+    return *this;
+  }
+  template <typename F>
+  SafeWriteResult& fault(F&& handler) noexcept { return fail(handler); }
+  template <typename F>
+  SafeWriteResult& always(F&& handler) noexcept { handler(*this); return *this; }
+};
+`.trim();
+}