@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

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

@@ -0,0 +1,72 @@
+import { asilLevel, ASIL_THRESHOLDS } from "./asil.js";
+/** B6: No unconstrained goto (ISO 26262 Part 6, §7.4.8 — ASIL C+).
+ *
+ *  Scans for goto statements in emitted IR. Cuttlefish's only source of
+ *  goto is labeled break lowering (TS `break labelName;` → C++ `goto
+ *  __break_labelName;`). While this is a controlled use, ISO 26262 C+
+ *  restricts goto to specific patterns (forward, within the same block).
+ *  Reports each goto as an info-level diagnostic for awareness. */
+export function checkGoto(program, _ctx) {
+    const diags = [];
+    for (const fn of program.functions) {
+        if (asilLevel(fn.decorators) < ASIL_THRESHOLDS.unboundedLoop)
+            continue;
+        for (const stmt of fn.statements) {
+            scanForGoto(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) {
+                scanForGoto(stmt, method.name, diags);
+            }
+        }
+    }
+    return diags;
+}
+function scanForGoto(stmt, fnName, diags) {
+    if (!stmt || typeof stmt !== "object")
+        return;
+    // Check for goto in raw expressions (lowered from labeled break)
+    if (stmt.kind === "raw" && typeof stmt.value === "string") {
+        if (/\bgoto\s+\w+/.test(stmt.value)) {
+            const match = stmt.value.match(/\bgoto\s+(\w+)/);
+            const label = match ? match[1] : "unknown";
+            diags.push({
+                severity: "info",
+                code: "ISO26262_B6_GOTO",
+                message: `goto ${label} in ${fnName}() — lowered from labeled break`,
+                hint: "ISO 26262 C+ restricts goto. Consider restructuring with a flag variable or early return.",
+            });
+        }
+    }
+    // Check for the "labeled" statement kind (cuttlefish's IR representation
+    // of labeled break — the actual goto is emitted as a raw statement
+    // during rendering, but the labeled IR node is present at analysis time).
+    if (stmt.kind === "labeled" && typeof stmt.label === "string") {
+        diags.push({
+            severity: "info",
+            code: "ISO26262_B6_GOTO",
+            message: `Labeled break '${stmt.label}' in ${fnName}() will lower to goto`,
+            hint: "ISO 26262 C+ restricts goto. Consider restructuring with a flag variable or early return.",
+        });
+    }
+    // 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") {
+                    scanForGoto(item, fnName, diags);
+                }
+            }
+        }
+        else if (val && typeof val === "object" && typeof val.kind === "string") {
+            scanForGoto(val, fnName, diags);
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { ProgramIR, Diagnostic } from "../../api/index.js";
+import type { SafetyTransformContext } from "../../safety-hook.js";
+/** B2: No dynamic allocation after init (ISO 26262 Part 6, §7.4.11 — ASIL D).
+ *
+ *  Only checks functions decorated with @asilD.
+ *  Lower ASIL levels and QM functions are skipped. */
+export declare function checkDynamicAllocation(program: ProgramIR, _ctx: SafetyTransformContext): Diagnostic[];

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

@@ -0,0 +1,57 @@
+import { asilLevel, ASIL_THRESHOLDS } from "./asil.js";
+/** B2: No dynamic allocation after init (ISO 26262 Part 6, §7.4.11 — ASIL D).
+ *
+ *  Only checks functions decorated with @asilD.
+ *  Lower ASIL levels and QM functions are skipped. */
+export function checkDynamicAllocation(program, _ctx) {
+    const diags = [];
+    const initFnNames = new Set(["setup", "main", "__top_level__"]);
+    for (const fn of program.functions) {
+        if (initFnNames.has(fn.originalName))
+            continue;
+        if (asilLevel(fn.decorators) < ASIL_THRESHOLDS.dynamicAlloc)
+            continue;
+        for (const stmt of fn.statements) {
+            scanForAllocation(stmt, fn.originalName, diags);
+        }
+    }
+    for (const cls of program.classes) {
+        for (const method of cls.methods) {
+            if (!method.name || initFnNames.has(method.name))
+                continue;
+            if (asilLevel(method.decorators) < ASIL_THRESHOLDS.dynamicAlloc)
+                continue;
+            for (const stmt of method.statements) {
+                scanForAllocation(stmt, method.name, diags);
+            }
+        }
+    }
+    return diags;
+}
+function scanForAllocation(stmt, fnName, diags) {
+    if (!stmt || typeof stmt !== "object")
+        return;
+    if (stmt.kind === "raw" && typeof stmt.value === "string") {
+        if (/\bnew\s+[A-Z_]/.test(stmt.value) || /\bmalloc\s*\(/.test(stmt.value) || /\bcalloc\s*\(/.test(stmt.value)) {
+            diags.push({
+                severity: "error",
+                code: "ISO26262_B2_DYNAMIC_ALLOC",
+                message: `Dynamic allocation in ${fnName}(): ${stmt.value.trim().slice(0, 80)}`,
+                hint: "ASIL D forbids dynamic allocation after initialization. Pre-allocate in setup() or use a fixed-size buffer.",
+            });
+        }
+    }
+    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") {
+                    scanForAllocation(item, fnName, diags);
+                }
+            }
+        }
+        else if (val && typeof val === "object" && typeof val.kind === "string") {
+            scanForAllocation(val, fnName, diags);
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { ProgramIR, Diagnostic } from "../../api/index.js";
+import type { SafetyTransformContext } from "../../safety-hook.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 declare function checkInitCompleteness(program: ProgramIR, _ctx: SafetyTransformContext): Diagnostic[];

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;