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

package/dist/safety/asil-decorators.js

@@ -0,0 +1,32 @@
+export {};
+/** ASIL level annotations for functions — comment-based.
+ *
+ *  ASIL levels are declared via leading comment annotations rather than
+ *  TypeScript decorators because:
+ *  - TS decorators on function declarations produce TS1206 errors in the
+ *    VS Code language server and @typescript-eslint/parser
+ *  - Comment annotations work in any editor, any toolchain, without
+ *    `experimentalDecorators` or special config
+ *
+ *  The cuttlefish IR builder extracts these from leading comments via
+ *  extractAsilFromComments() in function-builder.ts.
+ *
+ *  Part B's ISO 26262 checkers (analyzeIR) read the resulting `decorators`
+ *  field on FunctionIR to decide which rules to enforce:
+ *
+ *    // @asilD → all rules enforced (recursion, heap, loops)
+ *    // @asilC → recursion + loops enforced (heap is ASIL D only)
+ *    // @asilB → recursion enforced
+ *    // @asilA → no rules enforced (quality-managed)
+ *    (no annotation) → no rules enforced (implicit QM)
+ *
+ *  Usage:
+ *    // @asilD
+ *    function engageBrake(): void {
+ *      safe.write(brakePin, 1);
+ *    }
+ *
+ *  These are documentation-only exports — they have no runtime behavior
+ *  and are never imported by user code. They exist so the ASIL level
+ *  names appear in type hints and IDE autocomplete.
+ */

package/dist/safety/authoring.d.ts

@@ -0,0 +1,85 @@
+export type { SafeVariable } from "./safe-variable-types.js";
+export type { SafeInt } from "./safe-int-types.js";
+import type { Pin } from "@typecad/hal";
+/** The pin argument safe.read accepts — a thin-HAL `GPIO`. A named alias so
+ *  the safety API's stringified type stays free of union syntax at call sites.
+ *  At runtime the safety package resolves the same `_pin: number` field via
+ *  the halInstances registry at IR time. */
+export type AnyPin = Pin;
+/** Two-tier fault taxonomy. Stable across safety standards (ISO 26262,
+ *  IEC 61508, DO-178C). The category is the coarse user-space routing axis;
+ *  the code is standard-specific detail.
+ *
+ *  Declared as TypeScript `enum` (not `const` object + type alias) so the
+ *  cuttlefish transpiler lowers these to a single C++ `enum class` definition
+ *  matching the runtime polyfill's enum, rather than emitting a conflicting
+ *  struct per usage scope. The transpiler's enum lowering and the polyfill's
+ *  enum class are structurally identical (same tag name, same enumerators,
+ *  same values). */
+export declare enum SafetyFaultCategory {
+    Ok = 1010580540,
+    Signal = 1515870810,
+    Integrity = 2779096485,
+    Timing = 3284386755,
+    System = 1437226410,
+    Configuration = 2857740885
+}
+export declare enum SafetyFaultCode {
+    Ok = 1010580540,
+    VoteDisagreement = 1515870810,
+    StuckHigh = 2779096485,
+    StuckLow = 3284386755,
+    PinModeMismatch = 1437226410,
+    PinModeUnknown = 2857740885,
+    WriteMismatch = 1012573635
+}
+export declare enum SafetyStatus {
+    Ok = 1515870810,
+    Fault = 2779096485
+}
+export interface SafeReadResult {
+    readonly status: SafetyStatus;
+    readonly value: number;
+    readonly category: SafetyFaultCategory;
+    readonly code: SafetyFaultCode;
+    /** Run handler iff status === Ok. Handler receives the full result. Returns the result (chainable). */
+    ok(handler: (r: SafeReadResult) => void): SafeReadResult;
+    /** Run handler iff status !== Ok. Handler receives the full result. Returns the result (chainable). */
+    fail(handler: (r: SafeReadResult) => void): SafeReadResult;
+    /** Alias of fail(). */
+    fault(handler: (r: SafeReadResult) => void): SafeReadResult;
+    /** Run handler unconditionally. Returns the result (chainable). */
+    always(handler: (r: SafeReadResult) => void): SafeReadResult;
+}
+export interface SafeWriteResult {
+    readonly status: SafetyStatus;
+    readonly code: SafetyFaultCode;
+    ok(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+    fail(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+    fault(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+    always(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+}
+/** Safe GPIO API. Compile-time construct only — the cuttlefish transpiler
+ *  intercepts safe.read and lowers it to a safety.read_safe HAL op. The
+ *  type annotation (rather than `as const`) gives `safe` a single object
+ *  type so member access doesn't lower to std::variant access — same reason
+ *  @typecad/ui's `ui` uses an explicit type annotation. */
+export declare const safe: {
+    /** Safe digital read: confirms the pin's recorded mode is INPUT or
+     *  INPUT_PULLUP (via the auto-populated mode table), performs a 2-of-3
+     *  vote via the strategy-injected __tc_gpio_read shim, returns a
+     *  SafeReadResult carrying any detected fault.
+     *
+     *  Accepts any thin-HAL GPIO regardless of its constructed flag set. The
+     *  runtime mode-table check (driven by the GPIO's construction flags)
+     *  rejects pins configured as OUTPUT (returns PinModeMismatch). */
+    read(pin: AnyPin): SafeReadResult;
+    /** Safe digital write with readback verification. Writes the value,
+     *  immediately reads the physical pin state back, and returns a
+     *  SafeWriteResult confirming the write succeeded or flagging a fault.
+     *
+     *  Verifies the pin's recorded mode is OUTPUT (returns PinModeMismatch
+     *  for non-output pins). On write/read mismatch, returns
+     *  WriteMismatch. */
+    write(pin: Pin, value: number): SafeWriteResult;
+};

package/dist/safety/authoring.js

@@ -0,0 +1,61 @@
+// Public API surface for cuttlefish safety — importable as
+// '@typecad/cuttlefish/safety' (the legacy '@typecad/safety' specifier is
+// still detected by the transpiler; detection is by name, no module
+// resolution happens).
+//
+// `safe` is a COMPILE-TIME CONSTRUCT ONLY. The cuttlefish transpiler
+// intercepts safe.read calls (via tryResolveSemanticCall → the safety hook's
+// resolveSemanticCall) and lowers them to safety.read_safe HAL ops. The
+// runtime stub below throws so importing `safe` from plain Node never
+// silently works — mirrors how @typecad/ui's ui.mount behaves.
+//
+// Part A v2: mode configuration belongs to @typecad/hal (Pin.asInput() etc.).
+// The safety engine owns only the verified read.
+/** Two-tier fault taxonomy. Stable across safety standards (ISO 26262,
+ *  IEC 61508, DO-178C). The category is the coarse user-space routing axis;
+ *  the code is standard-specific detail.
+ *
+ *  Declared as TypeScript `enum` (not `const` object + type alias) so the
+ *  cuttlefish transpiler lowers these to a single C++ `enum class` definition
+ *  matching the runtime polyfill's enum, rather than emitting a conflicting
+ *  struct per usage scope. The transpiler's enum lowering and the polyfill's
+ *  enum class are structurally identical (same tag name, same enumerators,
+ *  same values). */
+export var SafetyFaultCategory;
+(function (SafetyFaultCategory) {
+    SafetyFaultCategory[SafetyFaultCategory["Ok"] = 1010580540] = "Ok";
+    SafetyFaultCategory[SafetyFaultCategory["Signal"] = 1515870810] = "Signal";
+    SafetyFaultCategory[SafetyFaultCategory["Integrity"] = 2779096485] = "Integrity";
+    SafetyFaultCategory[SafetyFaultCategory["Timing"] = 3284386755] = "Timing";
+    SafetyFaultCategory[SafetyFaultCategory["System"] = 1437226410] = "System";
+    SafetyFaultCategory[SafetyFaultCategory["Configuration"] = 2857740885] = "Configuration";
+})(SafetyFaultCategory || (SafetyFaultCategory = {}));
+export var SafetyFaultCode;
+(function (SafetyFaultCode) {
+    SafetyFaultCode[SafetyFaultCode["Ok"] = 1010580540] = "Ok";
+    SafetyFaultCode[SafetyFaultCode["VoteDisagreement"] = 1515870810] = "VoteDisagreement";
+    SafetyFaultCode[SafetyFaultCode["StuckHigh"] = 2779096485] = "StuckHigh";
+    SafetyFaultCode[SafetyFaultCode["StuckLow"] = 3284386755] = "StuckLow";
+    SafetyFaultCode[SafetyFaultCode["PinModeMismatch"] = 1437226410] = "PinModeMismatch";
+    SafetyFaultCode[SafetyFaultCode["PinModeUnknown"] = 2857740885] = "PinModeUnknown";
+    SafetyFaultCode[SafetyFaultCode["WriteMismatch"] = 1012573635] = "WriteMismatch";
+})(SafetyFaultCode || (SafetyFaultCode = {}));
+export var SafetyStatus;
+(function (SafetyStatus) {
+    SafetyStatus[SafetyStatus["Ok"] = 1515870810] = "Ok";
+    SafetyStatus[SafetyStatus["Fault"] = 2779096485] = "Fault";
+})(SafetyStatus || (SafetyStatus = {}));
+class CompileTimeOnly extends Error {
+    constructor() {
+        super("cuttlefish safety: `safe` is a compile-time construct. It is lowered by the cuttlefish transpiler and has no runtime implementation.");
+    }
+}
+/** Safe GPIO API. Compile-time construct only — the cuttlefish transpiler
+ *  intercepts safe.read and lowers it to a safety.read_safe HAL op. The
+ *  type annotation (rather than `as const`) gives `safe` a single object
+ *  type so member access doesn't lower to std::variant access — same reason
+ *  @typecad/ui's `ui` uses an explicit type annotation. */
+export const safe = {
+    read(_pin) { throw new CompileTimeOnly(); },
+    write(_pin, _value) { throw new CompileTimeOnly(); },
+};

package/dist/safety/engine.d.ts

@@ -0,0 +1,3 @@
+import type { TranspilerSafetyHook } from "../safety-hook.js";
+export declare function registerSafetyEngine(): TranspilerSafetyHook;
+export type { TranspilerSafetyHook };

package/dist/safety/engine.js

@@ -0,0 +1,83 @@
+import { pinModeInterceptPass } from "./passes/pinMode-intercept.js";
+import { buildSafetyPolyfills } from "./runtime/polyfills.js";
+import { halInstances } from "../ir/build-ir-state.js";
+import { analyzeProgram } from "./iso26262/analyze.js";
+import { collectSafetyMetadata } from "./iso26262/collect.js";
+/** Resolve a safety.* HAL op to C++. MCU-agnostic: emits calls only to the
+ *  safety package's own __tc_safety_* helpers (never to target-specific
+ *  symbols like digitalRead). The strategy-injected __tc_gpio_read shim is
+ *  called from inside the voter polyfill, not from here.
+ *
+ *  `op.operation` is a closed union in cuttlefish's HALOpIR that does NOT
+ *  include safety.* ops (those are owned by this package). The dispatch in
+ *  routeHALOp() uses string-prefix matching, so by the time we get here the
+ *  operation is a safety.* string — cast to `string` so the switch is an
+ *  open comparison. Field access goes through a generic record view because
+ *  the safety op shapes are not part of the HALOpIR union. */
+function resolveSafetyOp(op) {
+    const operation = op.operation;
+    const fields = op;
+    switch (operation) {
+        case "safety.record_pin_mode":
+            // mode is a TrackedMode enum value (numeric) — emitted as-is.
+            return { code: `__tc_safety_record_pin_mode(${fields.pin}, ${fields.mode});` };
+        case "safety.read_safe":
+            return { expression: `__tc_safety::read_safe(${fields.pin})` };
+        case "safety.write_verify":
+            return { expression: `__tc_safety::write_verify(${fields.pin}, ${fields.value})` };
+        default:
+            return undefined;
+    }
+}
+/** Resolve a Pin-instance argument to its pin number at IR time, using the
+ *  same halInstances registry the HAL layer uses to resolve `this._pin`
+ *  inside Pin method bodies. Returns undefined for args that aren't tracked
+ *  Pin instances (the caller emits a diagnostic in that case). Also accepts
+ *  literal numbers as a fallback (for code that constructs a Pin inline at
+ *  the call site, e.g. safe.read(Pin.fromPort('PD2')) — though the idiomatic
+ *  form is to assign the Pin to a local first). */
+function resolvePinArg(arg) {
+    if (typeof arg === "number")
+        return arg;
+    if (typeof arg === "string") {
+        // Identifier — look up in halInstances for a Pin instance with _pin.
+        const inst = halInstances.get(arg);
+        if (inst) {
+            const pin = inst.fieldValues.get("_pin") ?? inst.fieldValues.get("pin");
+            if (pin !== undefined)
+                return Number(pin);
+        }
+    }
+    return undefined;
+}
+/** Lower a safe.* TS call to a HAL op. Called from tryResolveSemanticCall
+ *  (hal-plugins.ts) when the callee resolves to the @typecad/safety package. */
+function resolveSemanticCall(callee, args) {
+    // `safe.read(Pin)` → safety.read_safe (pin resolved at IR time)
+    if (callee === "safe.read") {
+        const pin = resolvePinArg(args[0]);
+        if (pin === undefined)
+            return undefined;
+        return { operation: "safety.read_safe", pin };
+    }
+    // `safe.write(OutputPin, value)` → safety.write_verify
+    // value may be a number (literal) or string (rendered C++ expression text)
+    if (callee === "safe.write") {
+        const pin = resolvePinArg(args[0]);
+        if (pin === undefined)
+            return undefined;
+        const value = args[1] ?? 0;
+        return { operation: "safety.write_verify", pin, value };
+    }
+    return undefined;
+}
+export function registerSafetyEngine() {
+    return {
+        transformIR: pinModeInterceptPass,
+        resolveSafetyOp,
+        resolveSemanticCall,
+        buildPolyfills: buildSafetyPolyfills,
+        analyzeIR: analyzeProgram,
+        collectSafetyMetadata,
+    };
+}

package/dist/safety/hal/ops.d.ts

@@ -0,0 +1,48 @@
+/** 5-value pin mode, mapped from gpio.configure's flag tokens at IR time.
+ *  Numeric so the voter switches on enum values (no strcmp at runtime). The
+ *  values are 32-bit Hamming-distance constants (0x5A5A5A5A etc.) chosen for
+ *  SEU resistance — a single-bit flip never lands on another valid mode.
+ *  This makes the C++ mode table 4 bytes/pin (~1 KB for the 255-entry table
+ *  on AVR, which has 2 KB SRAM). That is a deliberate trade-off vs 1-byte
+ *  storage: the SEU resistance is the whole point of the safety package.
+ *  Matches the C++ enum class TrackedMode in runtime/mode-table.ts. */
+export declare enum TrackedMode {
+    Unknown = 0,
+    Input = 1515870810,
+    Output = 2779096485,
+    InputPullup = 1010580540,
+    InputPulldown = 3284386755
+}
+/** Map gpio.configure flag-token text ("GPIO.INPUT | GPIO.PULL_UP", the
+ *  thin GPIO constructor's resolved flags) to the TrackedMode enum. Used by
+ *  the intercept pass at IR time. Direction wins over pulls; combos with no
+ *  tracked equivalent (open-drain, runtime expressions) map to Unknown so
+ *  the table still gets a fresh entry. */
+export declare function mapFlagTokens(flags: string): TrackedMode;
+/** Companion op injected after every gpio.set_mode by the pinMode-intercept
+ *  pass. Records the mode in the runtime safety mode table. */
+export interface SafetyRecordPinModeOp {
+    operation: "safety.record_pin_mode";
+    pin: number;
+    /** TrackedMode enum value (numeric) — mapped at IR time from the
+     *  gpio.set_mode op's mode string. */
+    mode: TrackedMode;
+}
+/** Op produced by `safe.read(Pin)`. Resolves to a C++ expression returning
+ *  a SafeReadResult. The pin number is resolved at IR time from the Pin
+ *  instance via the halInstances registry. */
+export interface SafetyReadSafeOp {
+    operation: "safety.read_safe";
+    pin: number;
+}
+/** Op produced by `safe.write(OutputPin, value)`. Resolves to a C++ expression
+ *  returning a SafeWriteResult. The pin number is resolved at IR time from the
+ *  Pin instance via the halInstances registry. The value may be a numeric
+ *  literal or a string containing the rendered C++ expression text (e.g.
+ *  "r.value", "x + 1"). */
+export interface SafetyWriteVerifyOp {
+    operation: "safety.write_verify";
+    pin: number;
+    value: number | string;
+}
+export type SafetyHALOp = SafetyRecordPinModeOp | SafetyReadSafeOp | SafetyWriteVerifyOp;

package/dist/safety/hal/ops.js

@@ -0,0 +1,46 @@
+// Safety HAL op definitions. These are dispatched by their `operation` string
+// prefix ("safety.*") via routeHALOp() in cuttlefish core. The strategy layer
+// NEVER resolves them — they are resolved by the safety package's
+// resolveSafetyOp, which is MCU-agnostic (it emits calls only to the safety
+// package's own __tc_safety_* helpers and the strategy-injected
+// __tc_gpio_read shim — never to target-specific symbols like digitalRead).
+/** 5-value pin mode, mapped from gpio.configure's flag tokens at IR time.
+ *  Numeric so the voter switches on enum values (no strcmp at runtime). The
+ *  values are 32-bit Hamming-distance constants (0x5A5A5A5A etc.) chosen for
+ *  SEU resistance — a single-bit flip never lands on another valid mode.
+ *  This makes the C++ mode table 4 bytes/pin (~1 KB for the 255-entry table
+ *  on AVR, which has 2 KB SRAM). That is a deliberate trade-off vs 1-byte
+ *  storage: the SEU resistance is the whole point of the safety package.
+ *  Matches the C++ enum class TrackedMode in runtime/mode-table.ts. */
+export var TrackedMode;
+(function (TrackedMode) {
+    TrackedMode[TrackedMode["Unknown"] = 0] = "Unknown";
+    TrackedMode[TrackedMode["Input"] = 1515870810] = "Input";
+    TrackedMode[TrackedMode["Output"] = 2779096485] = "Output";
+    TrackedMode[TrackedMode["InputPullup"] = 1010580540] = "InputPullup";
+    TrackedMode[TrackedMode["InputPulldown"] = 3284386755] = "InputPulldown";
+})(TrackedMode || (TrackedMode = {}));
+/** Map gpio.configure flag-token text ("GPIO.INPUT | GPIO.PULL_UP", the
+ *  thin GPIO constructor's resolved flags) to the TrackedMode enum. Used by
+ *  the intercept pass at IR time. Direction wins over pulls; combos with no
+ *  tracked equivalent (open-drain, runtime expressions) map to Unknown so
+ *  the table still gets a fresh entry. */
+export function mapFlagTokens(flags) {
+    // Only a pure token list ("GPIO.INPUT | GPIO.PULL_UP") is statically
+    // classifiable — anything else (runtime expression) is Unknown.
+    if (!/^\s*GPIO\.[A-Z0-9_]+(\s*\|\s*GPIO\.[A-Z0-9_]+)*\s*$/.test(flags)) {
+        return TrackedMode.Unknown;
+    }
+    const output = flags.includes("GPIO.OUTPUT");
+    const input = flags.includes("GPIO.INPUT");
+    if (output && !input)
+        return TrackedMode.Output;
+    if (input || output) {
+        if (flags.includes("GPIO.PULL_UP"))
+            return TrackedMode.InputPullup;
+        if (flags.includes("GPIO.PULL_DOWN"))
+            return TrackedMode.InputPulldown;
+        return TrackedMode.Input;
+    }
+    return TrackedMode.Unknown;
+}

package/dist/safety/iso26262/analyze.d.ts

@@ -0,0 +1,13 @@
+import type { ProgramIR, Diagnostic } from "../../api/index.js";
+import type { SafetyTransformContext } from "../../safety-hook.js";
+/** Part B: ISO 26262 Part 6 software-rule checker.
+ *
+ *  Runs all checkers against the final transformed IR and returns aggregated
+ *  diagnostics. Each checker is independent — a failure in one does not
+ *  prevent the others from running.
+ *
+ *  Diagnostics with severity "error" abort the build (via
+ *  throwIfFatalDiagnostics in transpile.ts); "warning"/"info" are logged
+ *  but the build succeeds.
+ */
+export declare function analyzeProgram(program: ProgramIR, ctx: SafetyTransformContext): Diagnostic[];

package/dist/safety/iso26262/analyze.js

@@ -0,0 +1,29 @@
+import { checkRecursion } from "./recursion-checker.js";
+import { checkDynamicAllocation } from "./heap-checker.js";
+import { checkUnboundedLoops } from "./loop-checker.js";
+import { checkInitCompleteness } from "./init-checker.js";
+import { checkGoto } from "./goto-checker.js";
+/** Part B: ISO 26262 Part 6 software-rule checker.
+ *
+ *  Runs all checkers against the final transformed IR and returns aggregated
+ *  diagnostics. Each checker is independent — a failure in one does not
+ *  prevent the others from running.
+ *
+ *  Diagnostics with severity "error" abort the build (via
+ *  throwIfFatalDiagnostics in transpile.ts); "warning"/"info" are logged
+ *  but the build succeeds.
+ */
+export function analyzeProgram(program, ctx) {
+    const diags = [];
+    for (const checker of [checkRecursion, checkDynamicAllocation, checkUnboundedLoops, checkInitCompleteness, checkGoto]) {
+        try {
+            const results = checker(program, ctx);
+            diags.push(...results);
+        }
+        catch {
+            // A checker crash should not prevent other checkers from running.
+            // The diagnostic is lost; the build continues.
+        }
+    }
+    return diags;
+}

package/dist/safety/iso26262/asil.d.ts

@@ -0,0 +1,10 @@
+/** Determine the ASIL level of a function from its decorators.
+ *  Returns a numeric severity: D=4, C=3, B=2, A=1, QM/none=0.
+ *  Higher = more rules enforced. */
+export declare function asilLevel(decorators?: string[]): number;
+/** Minimum ASIL level at which each rule applies. */
+export declare const ASIL_THRESHOLDS: {
+    readonly recursion: 2;
+    readonly dynamicAlloc: 4;
+    readonly unboundedLoop: 3;
+};

package/dist/safety/iso26262/asil.js

@@ -0,0 +1,22 @@
+/** Determine the ASIL level of a function from its decorators.
+ *  Returns a numeric severity: D=4, C=3, B=2, A=1, QM/none=0.
+ *  Higher = more rules enforced. */
+export function asilLevel(decorators) {
+    if (!decorators)
+        return 0;
+    if (decorators.includes("asilD"))
+        return 4;
+    if (decorators.includes("asilC"))
+        return 3;
+    if (decorators.includes("asilB"))
+        return 2;
+    if (decorators.includes("asilA"))
+        return 1;
+    return 0;
+}
+/** Minimum ASIL level at which each rule applies. */
+export const ASIL_THRESHOLDS = {
+    recursion: 2, // B+ — recursion forbidden
+    dynamicAlloc: 4, // D only — heap forbidden after init
+    unboundedLoop: 3, // C+ — unbounded loops warned
+};

package/dist/safety/iso26262/collect.d.ts

@@ -0,0 +1,14 @@
+import type { ProgramIR } from "../../api/index.js";
+import type { SafetyTransformContext, SafetyMetadata } from "../../safety-hook.js";
+/** Part C: collect safety metadata for sidecar artifact generation.
+ *
+ *  Walks the program IR and collects structured metadata about each
+ *  safety-critical function (those with ASIL annotations):
+ *  - ASIL level (from // @asilD / @asilC / @asilB comments)
+ *  - Source location (TS file + line)
+ *  - Safety mechanisms used (safe.read, safe.write, SafeVariable, SafeInt)
+ *  - Rule check results (B1–B6 pass/warning/error)
+ *
+ *  The caller writes the returned metadata as a sidecar JSON file
+ *  alongside the emitted C++ artifact. */
+export declare function collectSafetyMetadata(program: ProgramIR, ctx: SafetyTransformContext): SafetyMetadata[];

package/dist/safety/iso26262/collect.js

@@ -0,0 +1,137 @@
+import { asilLevel } from "./asil.js";
+import { analyzeProgram } from "./analyze.js";
+/** Part C: collect safety metadata for sidecar artifact generation.
+ *
+ *  Walks the program IR and collects structured metadata about each
+ *  safety-critical function (those with ASIL annotations):
+ *  - ASIL level (from // @asilD / @asilC / @asilB comments)
+ *  - Source location (TS file + line)
+ *  - Safety mechanisms used (safe.read, safe.write, SafeVariable, SafeInt)
+ *  - Rule check results (B1–B6 pass/warning/error)
+ *
+ *  The caller writes the returned metadata as a sidecar JSON file
+ *  alongside the emitted C++ artifact. */
+export function collectSafetyMetadata(program, ctx) {
+    const functions = [];
+    // Run the analyzers to get current rule results per function
+    const diagnostics = analyzeProgram(program, ctx);
+    const diagsByFunction = new Map();
+    for (const d of diagnostics) {
+        // Extract function name from the message (format: "Recursion detected: ..."
+        // or "Dynamic allocation in fnName(): ...")
+        const fnMatch = d.message.match(/in (\w+)\(\)/);
+        const fnName = fnMatch ? fnMatch[1] : "";
+        if (fnName) {
+            if (!diagsByFunction.has(fnName)) {
+                diagsByFunction.set(fnName, []);
+            }
+            diagsByFunction.get(fnName).push(d);
+        }
+    }
+    const allRuleIds = ["B1_RECURSION", "B2_DYNAMIC_ALLOC", "B3_UNBOUNDED_LOOP", "B5_INIT_COMPLETENESS", "B6_GOTO"];
+    for (const fn of program.functions) {
+        const level = asilLevel(fn.decorators);
+        if (level === 0)
+            continue;
+        const asilName = level === 4 ? "D" : level === 3 ? "C" : level === 2 ? "B" : level === 1 ? "A" : "QM";
+        // Detect safety mechanisms used in this function
+        const mechanisms = detectMechanisms(fn);
+        // Build rule results: pass by default, override with diagnostics
+        const rules = {};
+        for (const ruleId of allRuleIds) {
+            const fullCode = `ISO26262_${ruleId}`;
+            const matchingDiags = (diagsByFunction.get(fn.originalName) ?? [])
+                .filter(d => d.code === fullCode);
+            if (matchingDiags.length > 0) {
+                // Use the first matching diagnostic (they're all the same rule)
+                rules[ruleId] = {
+                    severity: matchingDiags[0].severity,
+                    message: matchingDiags[0].message,
+                };
+            }
+            else {
+                rules[ruleId] = "pass";
+            }
+        }
+        functions.push({
+            name: fn.originalName,
+            asilLevel: asilName,
+            source: fn.sourceSpan ? {
+                tsFile: fn.sourceSpan.filePath,
+                tsLine: fn.sourceSpan.startLine,
+            } : undefined,
+            mechanisms,
+            rules,
+        });
+    }
+    // Also scan class methods
+    for (const cls of program.classes) {
+        for (const method of cls.methods) {
+            if (!method.name)
+                continue;
+            const level = asilLevel(method.decorators);
+            if (level === 0)
+                continue;
+            const asilName = level === 4 ? "D" : level === 3 ? "C" : level === 2 ? "B" : level === 1 ? "A" : "QM";
+            const mechanisms = detectMechanisms({ parameters: [], statements: method.statements });
+            const rules = {};
+            for (const ruleId of allRuleIds) {
+                rules[ruleId] = "pass";
+            }
+            functions.push({
+                name: `${cls.name}::${method.name}`,
+                asilLevel: asilName,
+                mechanisms,
+                rules,
+            });
+        }
+    }
+    return [{ functions }];
+}
+/** Scan a function's statements for safety-mechanism usage. */
+function detectMechanisms(fn) {
+    const mechanisms = new Set();
+    const scan = (stmt) => {
+        if (!stmt || typeof stmt !== "object")
+            return;
+        // HAL ops (safe.read → safety.read_safe, safe.write → safety.write_verify)
+        if (stmt.kind === "hal-op" && typeof stmt.operation === "string") {
+            if (stmt.operation === "safety.read_safe")
+                mechanisms.add("safe.read");
+            if (stmt.operation === "safety.write_verify")
+                mechanisms.add("safe.write");
+        }
+        // Raw expressions mentioning SafeVariable or SafeInt
+        if (stmt.kind === "raw" && typeof stmt.value === "string") {
+            if (/\bSafeVariable</.test(stmt.value))
+                mechanisms.add("SafeVariable");
+            if (/\bSafeInt/.test(stmt.value))
+                mechanisms.add("SafeInt");
+        }
+        // var_decl with cppType containing SafeVariable<SafeInt
+        if (stmt.kind === "var_decl" && typeof stmt.cppType === "string") {
+            if (/SafeVariable</.test(stmt.cppType))
+                mechanisms.add("SafeVariable");
+            if (/SafeInt/.test(stmt.cppType))
+                mechanisms.add("SafeInt");
+        }
+        // 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") {
+                        scan(item);
+                    }
+                }
+            }
+            else if (val && typeof val === "object" && typeof val.kind === "string") {
+                scan(val);
+            }
+        }
+    };
+    for (const stmt of fn.statements) {
+        scan(stmt);
+    }
+    return [...mechanisms].sort();
+}

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

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