@typecad/cuttlefish 1.0.0-alpha.7 → 1.0.0-alpha.8

package/dist/emit/route-hal-op.js

@@ -1,13 +1,26 @@
 // ---------------------------------------------------------------------------
 // Op routing — dispatch a HALOpIR to the right strategy resolver.
 //
-// display.* ops go to resolveDisplayOp (graphics-specific); everything else
-// goes to resolveHALOperation (the existing generic seam). Keeps the consumer
-// sites (expression-renderer, statement-renderer, render-expr) DRY.
+// display.* ops go to resolveDisplayOp (graphics-specific).
+// safety.*  ops go to the safety hook's resolveSafetyOp (when @typecad/safety
+//           is loaded) — NEVER to a per-target strategy, because the safety
+//           package is MCU-agnostic by construction.
+// everything else goes to resolveHALOperation (the existing generic seam).
+// Keeps the consumer sites (expression-renderer, statement-renderer,
+// render-expr) DRY.
 // ---------------------------------------------------------------------------
+import { getSafetyHook } from "../safety-hook.js";
 export function routeHALOp(op, strategy) {
-    if (typeof op.operation === "string" && op.operation.startsWith("display.")) {
-        return strategy.resolveDisplayOp?.(op);
+    if (typeof op.operation === "string") {
+        if (op.operation.startsWith("display.")) {
+            return strategy.resolveDisplayOp?.(op);
+        }
+        if (op.operation.startsWith("safety.")) {
+            // Safety ops are resolved by the @typecad/safety package via hook.
+            // Returns undefined if the package is not loaded (caller emits an
+            // unhandled-op warning).
+            return getSafetyHook()?.resolveSafetyOp?.(op);
+        }
     }
     return strategy.resolveHALOperation?.(op);
 }

package/dist/emit/snprintf-helpers.js

@@ -236,11 +236,14 @@ export function inferSnprintfArg(expr, strategy, scopeState, renderExpression, p
                         return { format: "%d", arg: renderExpression(expr), estimatedLength: 12, preludeLines: [] };
                     }
                 }
-                const arduinoIntFunctions = new Set([
-                    "digitalRead", "analogRead", "pulseIn", "pulseInLong",
-                    "Wire_available", "Serial_available",
+                const halIntFunctions = new Set([
+                    ...(strategy?.halCallNames?.() ?? new Set()),
+                    // pulseIn/pulseInLong and the Wire_available/Serial_available forms
+                    // are framework-specific suffix conventions; frameworks may add them
+                    // to halCallNames. Kept as a fallback here until all frameworks do.
+                    "pulseIn", "pulseInLong", "Wire_available", "Serial_available",
                 ]);
-                if (arduinoIntFunctions.has(funcName)) {
+                if (halIntFunctions.has(funcName)) {
                     return { format: "%d", arg: renderExpression(expr), estimatedLength: 12, preludeLines: [] };
                 }
             }

package/dist/emit/statement-renderer.d.ts

@@ -63,6 +63,14 @@ interface StatementRendererContext {
      * list. Optional so ad-hoc/test constructions still work.
      */
     diagnostics?: Diagnostic[];
+    /**
+     * Optional compliance context for A3-9-1 (fixed-width integer default).
+     * When provided and A3-9-1 is enforced, defaultNumericType() returns a
+     * fixed-width type instead of the legacy 'int'.
+     */
+    compliance?: {
+        isBanned(ruleId: string): boolean;
+    };
 }
 /**
  * Renders StatementIR nodes to C++ code strings.
@@ -83,6 +91,8 @@ export declare class StatementRenderer {
     private readonly interfaceFieldTypes;
     /** Shared emit-time diagnostics sink (see StatementRendererContext.diagnostics). */
     private readonly _diagnostics;
+    /** Compliance context for A3-9-1 fixed-width integer default. */
+    private readonly _compliance?;
     constructor(context: StatementRendererContext);
     /**
      * Gets the underlying expression renderer for direct use.

package/dist/emit/statement-renderer.js

@@ -116,6 +116,7 @@ export class StatementRenderer {
         this.namespaceNames = context.namespaceNames ?? new Set();
         this.interfaceFieldTypes = context.interfaceFieldTypes ?? new Map();
         this._diagnostics = context.diagnostics ?? [];
+        this._compliance = context.compliance;
         // Create expression renderer with shared context
         this.expressionRenderer = new ExpressionRenderer({
             strategy: context.strategy,
@@ -324,7 +325,7 @@ export class StatementRenderer {
                     this.expressionRenderer.pushPrelude([
                         `const char* ${idxVar}_keys[] = { ${keysArr} };`,
                     ]);
-                    return `for (${this.strategy.defaultNumericType()} ${idxVar} = 0; ${idxVar} < ${statement.keys.length}; ${idxVar}++)`;
+                    return `for (${this.strategy.defaultNumericType(this._compliance)} ${idxVar} = 0; ${idxVar} < ${statement.keys.length}; ${idxVar}++)`;
                 }
                 const varDecl = statement.variable;
                 if (varDecl.kind === "var_decl") {
@@ -485,6 +486,15 @@ export class StatementRenderer {
             const rawStmt = statement.callee.slice('__RAW_STMT__'.length);
             return forHeader ? rawStmt : `${rawStmt.endsWith(';') ? rawStmt : rawStmt + ';'}`;
         }
+        // Handle expression statements whose IR must render at EMIT time (not the
+        // build-time renderExprAsText). The safe.read().ok().fail() chain uses this:
+        // its lambda args can only render via the emit-time renderLambda (which
+        // produces [&](){...}), so the structured chain IR is carried as args[0]
+        // and rendered here via the expression renderer.
+        if (statement.callee === '__EXPR_STMT__' && statement.args.length >= 1) {
+            const exprText = this.expressionRenderer.render(statement.args[0], undefined, knownVariableTypes);
+            return forHeader ? exprText : `${exprText};`;
+        }
         // Awaited network markers (__WIFI_WAIT__/__HTTP_WAIT__) reaching the
         // plain renderer means the await sits outside an async state machine
         // (top-level await, or a position the state-machine splitter doesn't
@@ -658,13 +668,13 @@ export class StatementRenderer {
                     // that don't support std::vector → emit as a plain C-style array.
                     // Mutable arrays (.push/.pop/.indexOf) are rewritten to StaticArray<int> in
                     // the IR builder (via mutableArrayVars) and never reach this branch.
-                    const elementType = parsedElementString(rawType) ?? this.strategy.defaultNumericType();
+                    const elementType = parsedElementString(rawType) ?? this.strategy.defaultNumericType(this._compliance);
                     return forHeader
                         ? `${elementType} ${safeArrName}[] = { ${elements} }`
                         : `${elementType} ${safeArrName}[] = { ${elements} };`;
                 }
                 // Use "int" for "auto" element type since C arrays need explicit types
-                const arrayType = statement.initializer.elementType === "auto" ? this.strategy.defaultNumericType() : statement.initializer.elementType;
+                const arrayType = statement.initializer.elementType === "auto" ? this.strategy.defaultNumericType(this._compliance) : statement.initializer.elementType;
                 return forHeader
                     ? `${arrayType} ${safeArrName}[] = { ${elements} }`
                     : `${arrayType} ${safeArrName}[] = { ${elements} };`;
@@ -739,7 +749,7 @@ export class StatementRenderer {
             }
             // Handle spread array initializers
             if (statement.initializer.kind === "spread_array") {
-                let arrayType = statement.initializer.elementType === "auto" ? this.strategy.defaultNumericType() : statement.initializer.elementType;
+                let arrayType = statement.initializer.elementType === "auto" ? this.strategy.defaultNumericType(this._compliance) : statement.initializer.elementType;
                 const spreadName = this.expressionRenderer.render(statement.initializer.spreadExpr, calleeTransformer, knownVariableTypes);
                 if (statement.initializer.elementType === "auto" && knownVariableTypes && statement.initializer.spreadExpr.kind === "identifier") {
                     const srcInfo = knownVariableTypes.get(statement.initializer.spreadExpr.value);
@@ -892,11 +902,17 @@ export class StatementRenderer {
         if (this.stringEnumNames.has(typeName)) {
             return this.strategy.normalizeCppType("const char*");
         }
+        // A3-9-1: under autosar, substitute the platform's default numeric type
+        // for the legacy "int" spelling. The IR layer hardcodes "int" for number
+        // literals, so we catch it here at the renderer boundary.
+        if (typeName === "int" && this._compliance?.isBanned("A3-9-1")) {
+            return this.strategy.defaultNumericType(this._compliance);
+        }
         return this.strategy.normalizeCppType(typeName);
     }
     inferFieldType(value, parentName, fieldName) {
         return inferObjectFieldType(value, this.pointerVarTypes, this.knownFunctionReturnTypes, undefined, undefined, undefined, // largeEnumNames - would need to pass through
-        parentName, fieldName, this.strategy.defaultNumericType(), (o, n) => this.strategy.resolvePinType?.(o, n));
+        parentName, fieldName, this.strategy.defaultNumericType(this._compliance), (o, n) => this.strategy.resolvePinType?.(o, n));
     }
     /**
      * Transform console.log/error/warn calls based on target platform.

package/dist/emit/utils/async-state-machine.js

@@ -76,11 +76,23 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
     segments.push({ preStatements: currentPre, awaitedArgs: [] });
     const awaitCount = segments.filter((s) => s.awaitedCallee !== undefined).length;
     const stateCount = awaitCount + 1; // STATE_0 … STATE_{awaitCount}; cyclic loops back, linear adds STATE_DONE
+    // State enum is emitted as `enum class State` (AUTOSAR A7-2-1), so all
+    // references must be scope-qualified as `State::STATE_X`. The stateEnumList
+    // (used inside `enum class State { ... }`) uses the bare names; everywhere
+    // else (assignments, case labels, comparisons) uses the qualified form.
     const stateNames = [];
-    for (let i = 0; i < stateCount; i++)
+    const qualifiedStateNames = [];
+    for (let i = 0; i < stateCount; i++) {
         stateNames.push(`STATE_${i}`);
-    if (!isCyclic)
+        qualifiedStateNames.push(`State::STATE_${i}`);
+    }
+    if (!isCyclic) {
         stateNames.push("STATE_DONE");
+        qualifiedStateNames.push("State::STATE_DONE");
+    }
+    const Q = (i) => qualifiedStateNames[i];
+    const Q_DONE = "State::STATE_DONE";
+    const Q_0 = "State::STATE_0";
     // Helper: render a non-await statement as a single C++ line
     const renderStmt = (stmt) => renderStatement(stmt, false, strategy, undefined, undefined, knownFunctionReturnTypes);
     // Collect edge-detection markers from segments
@@ -138,14 +150,14 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         const seg = segments[i];
         const lines = [];
         if (seg.awaitedCallee === undefined) {
-            lines.push(`${pad}_state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
+            lines.push(`${pad}_state = ${isCyclic ? Q_0 : Q_DONE};`);
             return lines;
         }
         const edge = edgeInfoMap.get(i);
         const tap = tapInfoMap.get(i);
         const net = netInfoMap.get(i);
         if (edge) {
-            lines.push(`${pad}_edgePrev_p${edge.pin} = digitalRead(${edge.pin});`);
+            lines.push(`${pad}_edgePrev_p${edge.pin} = ${strategy.readDigitalPin?.(String(edge.pin)) ?? `digitalRead(${edge.pin})`};`);
             if (edge.timeout !== null) {
                 lines.push(`${pad}_waitUntil = ${strategy.currentTimeMillis()} + ${edge.timeout};`);
             }
@@ -165,13 +177,13 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
             const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
             lines.push(`${pad}_waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
         }
-        lines.push(`${pad}_state = STATE_${i + 1};`);
+        lines.push(`${pad}_state = ${Q(i + 1)};`);
         return lines;
     };
     const caseLines = [];
     for (let i = 0; i < segments.length; i++) {
         const seg = segments[i];
-        const stateName = `STATE_${i}`;
+        const stateName = Q(i);
         const body = [];
         const edgePoll = i > 0 ? edgeInfoMap.get(i - 1) : undefined;
         const tapPoll = i > 0 ? tapInfoMap.get(i - 1) : undefined;
@@ -194,7 +206,7 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
                 ? `(${cond}) || ${strategy.currentTimeMillis()} >= _waitUntil`
                 : cond;
             body.push(`        {`);
-            body.push(`          int _cur = digitalRead(${edgePoll.pin});`);
+            body.push(`          int _cur = ${strategy.readDigitalPin?.(String(edgePoll.pin)) ?? `digitalRead(${edgePoll.pin})`};`);
             body.push(`          if (${fullCond}) {`);
             body.push(`            ${prevVar} = _cur;`);
             body.push(...runSegment(`            `));
@@ -242,13 +254,13 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         caseLines.push(`      case ${stateName}:`, `        {`, ...body, `        }`, `        break;`);
     }
     if (!isCyclic)
-        caseLines.push(`      case STATE_DONE:`, `        break;`);
+        caseLines.push(`      case ${Q_DONE}:`, `        break;`);
     const stateEnumList = stateNames.join(", ");
-    const isCompleteExpr = isCyclic ? "false" : "_state == STATE_DONE";
+    const isCompleteExpr = isCyclic ? "false" : `_state == ${Q_DONE}`;
     // Build constructor initializer list and edge/tap member declarations
     const edgeMemberArr = Array.from(edgeMembers);
     const tapMemberArr = Array.from(tapMembers.keys());
-    const inits = [`_state(STATE_0)`, `_waitUntil(0)`];
+    const inits = [`_state(${Q_0})`, `_waitUntil(0)`];
     for (const m of edgeMemberArr)
         inits.push(`${m}(LOW)`);
     for (const m of tapMemberArr)
@@ -263,7 +275,7 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         `// Async state machine for ${fnName}`,
         `class ${className} {`,
         `public:`,
-        `  enum State { ${stateEnumList} };`,
+        `  enum class State { ${stateEnumList} };`,
         `  ${className}() : ${ctorInitList} {}`,
         `  void run() {`,
         `    switch (_state) {`,
@@ -271,7 +283,7 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         `    }`,
         `  }`,
         `  bool isComplete() const { return ${isCompleteExpr}; }`,
-        `  void reset() { _state = STATE_0; _waitUntil = 0;${edgeResetList}${tapResetList} }`,
+        `  void reset() { _state = ${Q_0}; _waitUntil = 0;${edgeResetList}${tapResetList} }`,
         `private:`,
         `  State _state;`,
         `  unsigned long _waitUntil;`,
@@ -394,6 +406,21 @@ function netWaitInfo(op, strategy) {
             }
             break;
         }
+        case "worker.submit": {
+            // Worker offload (Phase 3). `await worker.submit(fn, arg)` rewrites to:
+            // submit the worker (start), then poll worker.done on the same handle.
+            // The submit op is emitted verbatim as the start line; the poll predicate
+            // is worker.done(handle) carrying the SAME handleId. This is a predicate-
+            // poll resume (same per-frame cost as net/timer awaits), NOT an ISR-driven
+            // resume — that defers with DMA-backed awaits.
+            const submit = routeHALOp(op, strategy);
+            // Carry the handle through to the poll so submit + done agree on the slot.
+            const poll = route({ operation: "worker.done", handleId: o.handleId })?.expression ?? null;
+            if (submit?.code && poll) {
+                return { startLines: [submit.code], pollCond: poll, timeoutExpr: null };
+            }
+            break;
+        }
     }
     // Fallback: run the blocking form immediately and complete on the next tick.
     const blocking = routeHALOp(op, strategy);

package/dist/framework-package.js

@@ -50,6 +50,8 @@ export function loadFrameworkPackage(packageName, fromDir = process.cwd()) {
             } : undefined,
             classNameMapBuilder: typeof mod.buildClassNameMap === "function" ? mod.buildClassNameMap : undefined,
             libDeclGenerator: typeof mod.tryGenerateLibDecl === "function" ? mod.tryGenerateLibDecl : undefined,
+            doctor: typeof mod.doctor === "function" ? mod.doctor : undefined,
+            licenses: typeof mod.licenses === "function" ? mod.licenses : undefined,
         };
         setLoadedFramework(framework);
         registerPlatformStrategy(strategy);

package/dist/framework-registry.d.ts

@@ -14,6 +14,16 @@ export interface LoadedFramework {
     classNameMapBuilder?: (imports: any[]) => Map<string, string>;
     /** Framework library .d.ts declaration generation */
     libDeclGenerator?: (modulePath: string, file: string) => string | undefined;
+    /**
+     * Optional subcommand presenters owned by the framework. Cuttlefish dispatches
+     * `cuttlefish doctor` / `cuttlefish licenses` to these when the loaded
+     * framework provides them; otherwise it prints a no-support message. Each
+     * framework decides what (if anything) these do — e.g. framework-arduino
+     * checks arduino-cli + board core (doctor) and scans Arduino library licenses
+     * (licenses).
+     */
+    doctor?: () => void;
+    licenses?: (strict: boolean, all: boolean) => void;
 }
 /**
  * Resolves framework-specific library imports (e.g., Arduino libraries).
@@ -32,6 +42,13 @@ export interface FrameworkToolchain {
     compile(options: ToolchainOptions): CompileResult;
     upload?(options: ToolchainOptions): UploadResult;
     monitor?(options: ToolchainOptions): void;
+    /**
+     * Optional: launch an interactive debugger session for the last build
+     * (e.g. `west debug`). Not invoked by the standard build/compile flow;
+     * powers an explicit debug-attach entry point. Frameworks that support
+     * source-level debugging implement this to spawn their native debugger.
+     */
+    debug?(options: ToolchainOptions): void;
 }
 export declare function setLoadedFramework(framework: LoadedFramework): void;
 export declare function getLoadedFramework(): LoadedFramework;

package/dist/ir/adc-range-validation.js

@@ -4,6 +4,7 @@
 // Detects comparisons against analogRead() values that exceed the board's
 // ADC resolution (e.g., comparing to > 1023 on a 10-bit Arduino Uno).
 // ---------------------------------------------------------------------------
+import { hasLoadedFramework, getLoadedFramework } from '../framework-registry.js';
 /**
  * Get ADC configuration from board constants.
  */
@@ -41,7 +42,19 @@ function isAnalogRead(expr) {
         return op === 'adc.read' || op === 'adc.read_voltage';
     }
     if (expr.kind === 'raw') {
-        return /analogRead\s*\(/.test(expr.value);
+        const value = expr.value;
+        // Ask the loaded framework which call names produce an ADC read; fall back
+        // to the Wiring-derived analogRead when no framework is loaded.
+        const frameworkNames = hasLoadedFramework()
+            ? getLoadedFramework().strategy.analogReadCallNames?.()
+            : undefined;
+        const names = frameworkNames ?? new Set(['analogRead']);
+        for (const name of names) {
+            const re = new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\(`);
+            if (re.test(value))
+                return true;
+        }
+        return false;
     }
     return false;
 }

package/dist/ir/build-ir-state.d.ts

@@ -78,6 +78,7 @@ export declare class CompilationContext {
     floatVariables: Set<string>;
     snprintfCounter: number;
     callbackPlaceholderCounter: number;
+    bleCharCounter: number;
     activeStrategy: PlatformStrategy | null;
     restParamFunctions: Map<string, string>;
     /**

package/dist/ir/build-ir-state.js

@@ -65,6 +65,12 @@ export class CompilationContext {
         this.floatVariables = new Set();
         this.snprintfCounter = 0;
         this.callbackPlaceholderCounter = 0;
+        // BLE characteristic index counter — persists across separate Ble.server()
+        // calls so a multi-characteristic server (one server() per char, the common
+        // ble-demo pattern) gets unique sequential indices instead of every char
+        // clobbering slot 0. Read by the server()/characteristic() resolver branches
+        // in hal-parser.ts. Reset per file in hal-emitter.ts with the other counters.
+        this.bleCharCounter = 0;
         this.activeStrategy = null;
         this.restParamFunctions = new Map();
         /**
@@ -246,6 +252,14 @@ export function setCurrentBoardConstants(v) {
                 pinAliasMap.set(name, num);
                 mcuPinForwardMap.set(name, num);
                 mcuPinReverseMap.set(num, name);
+                // Register an identifier-safe variant so that pins whose canonical
+                // name is not a legal JS identifier (e.g. nRF52840 "P0.28") can be
+                // imported under their underscore form (P0_28). See "Pin Naming
+                // Conventions" in the root AGENTS.md.
+                const identName = name.replace(/[.\s-]/g, "_");
+                if (identName !== name) {
+                    pinAliasMap.set(identName, num);
+                }
             }
         }
     }

package/dist/ir/build-ir.js

@@ -443,14 +443,14 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
                         }
                     }
                 }
-                // Track HAL instances imported from board packages and framework stubs
-                // so the HAL resolver can resolve them to Arduino C++ names.
+                // Track HAL instances imported from board packages and framework HAL
+                // subpaths so the HAL resolver can resolve them to framework C++ names.
                 // The `@typecad/board` virtual import resolves to the board package, so it
                 // also registers pin aliases (LED, etc.). Case-insensitive on the scope.
                 const lowerSpecifier = moduleSpecifier.toLowerCase();
                 const isHALSource = lowerSpecifier.startsWith('@typecad/board-')
-                    || lowerSpecifier === '@typecad/framework-arduino/arduino'
-                    || lowerSpecifier === '@typecad/board';
+                    || lowerSpecifier === '@typecad/board'
+                    || /^@typecad\/framework-[a-z0-9-]+\/(arduino|hal|gpio)$/.test(lowerSpecifier);
                 // UI authoring namespace: `import { ui } from "@typecad/ui"`. The `ui`
                 // value is a compile-time construct (its calls are intercepted by
                 // tryResolveUICall); it must NOT be emitted as a C++ struct/value.

package/dist/ir/call-graph.js

@@ -159,6 +159,22 @@ export function buildCallGraph(program) {
             }
         }
     }
+    // Registered callbacks from the HAL resolver (e.g. the arrow function passed
+    // to `Ble.characteristic(...).onRead(() => readTemp())`) are NOT present in
+    // top-level statements — they ride in `program.registeredCallbacks` and are
+    // later hoisted to file-scope `*_isr_*` functions by top-level-prep. The
+    // placeholder name (`__CALLBACK_N__`) is what surfaces in top-level deps,
+    // not the identifiers the callback body references (e.g. a free function
+    // like `readTemp`). Without this scan those references are invisible to the
+    // call graph: the function survives the hoist (its call sits inside the
+    // emitted ISR) but is tree-shaken as unreachable, and g++ later reports it
+    // "not declared in this scope". Attach their body identifiers to
+    // __top_level__ since the callbacks execute from the top-level entry path.
+    for (const rc of (program.registeredCallbacks ?? [])) {
+        for (const id of collectExpressionIdentifiers(rc.callbackIR)) {
+            topLevelDependencies.add(id);
+        }
+    }
     nodes.set("__top_level__", {
         name: "__top_level__",
         kind: "variable",

package/dist/ir/expression-to-ir.js

@@ -12,6 +12,7 @@ import { tryLowerRegisterRead } from "./transformers/register-assignment.js";
 import { tryLowerArrayAndStringMethods } from "./transformers/array-methods.js";
 import { collectReturns, inferExprCppType, typeNodeToCppType } from "./type-resolution.js";
 import { parseCppType, elementOf, renderCppType, bareType, parsedIsPointer, parsedIsVector, parsedIsMap, parsedIsSet, parsedIsTuple, parsedIsStdString, parsedElementString, parsedBareString, isContainer } from "../api/shared/cpp-type-ir.js";
+import { hasSafetyHook, requireSafetyHook } from "../safety-hook.js";
 function resolveExprCppType(expr) {
     if (ts.isNonNullExpression(expr) || ts.isParenthesizedExpression(expr)) {
         return resolveExprCppType(expr.expression);
@@ -184,6 +185,143 @@ function resolveCallReturnTypeForNullGuard(call, sourceText) {
     }
     return undefined;
 }
+/** The SafeReadResult/SafeWriteResult chain methods whose lambda args must
+ *  render inline (preserving closure captures). Detected on the TS chain to
+ *  decide whether to take the structured-receiver path. */
+const SAFETY_RESULT_CHAIN_METHODS = new Set(["ok", "fail", "fault", "always"]);
+/** Detect `safe.<read|write>(...).<ok|fail|fault|always>(handler)...` chains
+ *  and build them as nested method-call IR nodes with a STRUCTURED receiverExpr
+ *  (not a flattened callee string). This preserves inner lambda args so the
+ *  emit pipeline can render them inline via renderLambda.
+ *
+ *  Returns null when the expression is not a safe.* call chained with at least
+ *  one result method (terminal safe.read/safe.write are handled by the
+ *  statement/var-decl interceptors; non-safe chains use the generic path). */
+function tryResolveSafetyChain(expr, sourceText, diagnostics, pointerVars) {
+    if (!hasSafetyHook())
+        return null;
+    const chain = [];
+    let cur = expr;
+    while (ts.isCallExpression(cur) && ts.isPropertyAccessExpression(cur.expression)) {
+        chain.push({ methodName: cur.expression.name.text, callNode: cur });
+        cur = cur.expression.expression;
+    }
+    // After the loop, `cur` is the innermost receiver. For a safe.* chain, the
+    // last-pushed chain element is the safe.read/safe.write root (its
+    // callNode.expression.expression is the identifier `safe`). Identify it.
+    if (chain.length === 0)
+        return null;
+    const root = chain[chain.length - 1];
+    const rootCall = root.callNode;
+    // rootCall.expression is `safe.read` (PropertyAccess); rootCall.expression.expression
+    // must be the identifier `safe` for this to be a safe.* root.
+    // The root method is read/write; the links above it (chain[0..length-2]) must
+    // include at least one result-chain method (ok/fail/fault/always).
+    const resultLinks = chain.slice(0, chain.length - 1);
+    const hasChainMethod = resultLinks.some((link) => SAFETY_RESULT_CHAIN_METHODS.has(link.methodName));
+    if (!hasChainMethod)
+        return null;
+    // Resolve the safe.<method>(...) root to a hal-expr (the same way variables.ts
+    // does for `const r = safe.read(pin)`). This becomes the innermost receiver.
+    const rootPropAccess = rootCall.expression;
+    const safeMethod = rootPropAccess.name.text;
+    const argValues = rootCall.arguments.map((a) => {
+        if (ts.isNumericLiteral(a))
+            return Number(a.text);
+        if (ts.isStringLiteral(a))
+            return a.text;
+        if (a.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (a.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+        if (ts.isIdentifier(a))
+            return a.text;
+        return a.getText();
+    });
+    const op = requireSafetyHook().resolveSemanticCall?.(`safe.${safeMethod}`, argValues);
+    // If the hook couldn't resolve the pin (halInstances not yet populated for
+    // this identifier at this point in IR building), fall back to rendering the
+    // root verbatim. The chain structure (with inline lambdas) is still correct;
+    // only the root's HAL resolution is deferred. This happens for multi-link
+    // chains where the resolver runs before the pin's HAL instance is registered.
+    let receiver;
+    if (op) {
+        receiver = { kind: "hal-expr", operation: op };
+    }
+    else {
+        // Best-effort: resolve the pin number directly from halInstances (the hook's
+        // resolvePinArg does the same lookup, but calling it directly here avoids the
+        // hook's early-return on unresolved pins).
+        const pinArg = argValues[0];
+        let pinNum;
+        if (typeof pinArg === "string") {
+            const inst = halInstances.get(pinArg);
+            if (inst) {
+                const pv = inst.fieldValues.get("_pin") ?? inst.fieldValues.get("pin");
+                if (pv !== undefined)
+                    pinNum = Number(pv);
+            }
+        }
+        else if (typeof pinArg === "number") {
+            pinNum = pinArg;
+        }
+        if (pinNum !== undefined) {
+            // Build the op manually now that we have the pin.
+            const fallbackOp = safeMethod === "read"
+                ? { operation: "safety.read_safe", pin: pinNum }
+                : { operation: "safety.write_verify", pin: pinNum, value: argValues[1] ?? 0 };
+            receiver = { kind: "hal-expr", operation: fallbackOp };
+        }
+        else {
+            // Last resort: verbatim text. The chain renders but the root won't have
+            // resolved to __tc_safety::read_safe — acceptable degradation.
+            receiver = { kind: "raw", value: rootCall.getText() };
+        }
+    }
+    // The root renders as __tc_safety::read_safe(pin) — render it to text so the
+    // callee string (used for non-receiverExpr consumers like type inference) is
+    // correct.
+    const rootText = renderExprAsText(receiver);
+    // Build nested method-call nodes bottom-up over the RESULT links only
+    // (chain[0..length-2], excluding the root at chain[length-1]). chain[0] is the
+    // outermost call (e.g. .fail); we build from the innermost result link outward.
+    for (let i = resultLinks.length - 1; i >= 0; i--) {
+        const link = resultLinks[i];
+        // Render this link's args as IR (lambdas become lambda IR nodes that
+        // renderLambda handles at emit time).
+        const argIRs = link.callNode.arguments.map((a) => expressionToIR(a, sourceText, diagnostics, pointerVars));
+        // Set concrete param types on lambda args so renderLambda emits
+        // `const SafeReadResult& r` instead of `auto r`. Generic lambdas (auto
+        // params) require C++14; AVR's gnu++11 doesn't support them. The chain
+        // knows the result type from the root (read -> SafeReadResult,
+        // write -> SafeWriteResult).
+        const resultType = safeMethod === "read" ? "SafeReadResult" : "SafeWriteResult";
+        for (const argIR of argIRs) {
+            if (argIR.kind === "lambda" && argIR.params) {
+                for (const p of argIR.params) {
+                    if (!p.cppType || p.cppType === "auto") {
+                        p.cppType = `const ${resultType}&`;
+                    }
+                }
+            }
+        }
+        // Build a callee string for backward-compat with consumers that read
+        // method-call.callee. The receiver text is rootText for the innermost link,
+        // or the prior receiver's rendered text for outer links.
+        const priorCallee = i === resultLinks.length - 1
+            ? rootText
+            : renderExprAsText(receiver);
+        const callee = `${priorCallee}.${escapeCppKeyword(link.methodName, new Set())}`;
+        receiver = {
+            kind: "method-call",
+            callee,
+            args: argIRs,
+            methodName: link.methodName,
+            receiverExpr: receiver,
+        };
+    }
+    return receiver;
+}
 export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new Map()) {
     function emitUnsupportedExpression(message) {
         diagnostics.push(makeDiagnostic(sourceText, expr.pos, message, "error", "TS2CPP_UNSUPPORTED_EXPR"));
@@ -953,6 +1091,18 @@ export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new
         };
     }
     if (ts.isCallExpression(expr)) {
+        // ---- safe.read/safe.write chained with .ok/.fail/.fault/.always ----
+        // Method chains like `safe.read(pin).ok(r => {...}).fail(r => {...})` cannot
+        // use the generic method-call builder because it flattens the receiver into
+        // a callee STRING (expression-to-ir.ts ~line 1475), destroying inner lambda
+        // args (they become `/* __lambda__ */` placeholders baked into the callee
+        // text). This resolver detects a safe.* call followed by a chain of fluent
+        // result methods and builds it bottom-up as nested method-call nodes with a
+        // STRUCTURED receiverExpr, so the emit pipeline renders each lambda arg
+        // inline via renderLambda (preserving closure captures).
+        const safetyChain = tryResolveSafetyChain(expr, sourceText, diagnostics, pointerVars);
+        if (safetyChain)
+            return safetyChain;
         // ---- rawCppExpr() — compile-time C++ injection in expression context ----
         // Mirrors the statement-position rawCpp()/__EMIT__ path, but emits the raw
         // text as an expression (e.g. for IDF macros like WIFI_INIT_CONFIG_DEFAULT()

package/dist/ir/function-builder.js

@@ -163,6 +163,7 @@ export function functionDeclarationToIR(node, fileName, sourceText, diagnostics,
         const elementType = restParam.cppType.replace(/^(?:const\s+)?std::vector<(.+)>&?$/, "$1");
         restParamFunctions.set(node.name.text, elementType);
     }
+    const fnDecorators = extractAsilFromComments(node, sourceText);
     return {
         originalName: node.name.text,
         isAsync,
@@ -174,8 +175,29 @@ export function functionDeclarationToIR(node, fileName, sourceText, diagnostics,
         ...(fnTypeParams && fnTypeParams.length > 0 ? { typeParameters: fnTypeParams } : {}),
         ...(isGenerator ? { isGenerator: true } : {}),
         ...(isExported ? { isExported: true } : {}),
+        ...(fnDecorators && fnDecorators.length > 0 ? { decorators: fnDecorators } : {}),
     };
 }
+/** Extract ASIL annotations from leading comments (e.g. `// @asilD`).
+ *
+ *  Uses comment-based annotations instead of TypeScript decorators because
+ *  TS decorators on function declarations produce TS1206 errors in the VS Code
+ *  language server and the @typescript-eslint/parser (both reject decorators
+ *  on functions — only class/method/property decorators are supported).
+ *  Comment annotations are valid TypeScript in any context, any editor, and
+ *  any toolchain — no false-positive errors. */
+function extractAsilFromComments(node, sourceText) {
+    const comments = extractNodeComments(node, sourceText);
+    const names = [];
+    for (const comment of comments.leadingComments) {
+        // Match `// @asilD`, `// @asilC`, `// @asilB`, `// @asilA`, `// @asilQM`
+        const match = comment.match(/@(asil[DCBAQM])/i);
+        if (match) {
+            names.push(match[1]);
+        }
+    }
+    return names.length > 0 ? names : undefined;
+}
 export function variableAsFunctionToIR(node, fileName, sourceText, diagnostics, functionReturnTypes, typeAliasNodes, boilerplates, pointerVars = new Map(), lowerStatementList) {
     const functionExpressionDeclarations = node.declarationList.declarations.filter((declaration) => {
         if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {