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

package/dist/emit/emitters/function-emitter-impl.js

@@ -5,6 +5,7 @@ import { escapeCppKeyword } from "../../utils/strings.js";
 import { parsedIsPlainStructType } from "../../api/shared/cpp-type-ir.js";
 import { entryHasUI } from "../../ui-hook.js";
 import { activeNamespaceNames } from "../../ir/build-ir-state.js";
+import { buildCoopSchedInjection } from "../../api/shared/coop-scheduler.js";
 export function emitPostClassDeclarations(ctx) {
     const { strategy, effectiveEmitMode, mappedFunctions, isEntryFile, topLevelScope } = ctx;
     const platformReservedNames = strategy.reservedNames();
@@ -31,6 +32,12 @@ export function emitPostClassDeclarations(ctx) {
     if (ctx.promotedVarDecls.size > 0) {
         for (const [varName, info] of ctx.promotedVarDecls) {
             appendSourceLine(ctx, `${info.cppType} ${escapeCppKeyword(varName, platformReservedNames)} = {};`);
+            // Seed the top-level scope's type map so subsequent assign rendering
+            // (e.g. the deferred `c = SafeInt(0)` initializer) can resolve the
+            // variable's type and inject template args / casts via
+            // renderValueForTarget. Without this, type-aware rendering of promoted
+            // vars is unreachable (inferLvalueCppType returns undefined).
+            ctx.topLevelScope.knownVariableTypes.set(varName, { cppType: info.cppType });
         }
         appendSourceLine(ctx, "");
     }
@@ -62,7 +69,7 @@ export function emitPostClassDeclarations(ctx) {
             // Still register the field types so downstream rendering (e.g. string-concat
             // wrapping via interfaceFieldTypes) can resolve property accesses on the var.
             const fieldTypeEntries = statement.initializer.fields.map((field) => {
-                const inferred = inferObjectFieldType(field.value, ctx.globalPointerVarTypes, ctx.knownFunctionReturnTypes, ctx.knownTopLevelObjectTypes, ctx.knownTopLevelObjectFields, ctx.largeEnumNames, statement.name, field.name, strategy.defaultNumericType(), (o, n) => strategy.resolvePinType?.(o, n));
+                const inferred = inferObjectFieldType(field.value, ctx.globalPointerVarTypes, ctx.knownFunctionReturnTypes, ctx.knownTopLevelObjectTypes, ctx.knownTopLevelObjectFields, ctx.largeEnumNames, statement.name, field.name, strategy.defaultNumericType(ctx.compliance.isEnabled() ? ctx.compliance : undefined), (o, n) => strategy.resolvePinType?.(o, n));
                 return [field.name, inferred];
             });
             if (hasExplicitNamedType) {
@@ -128,7 +135,12 @@ export function emitCallbackFunctions(ctx) {
             appendSourceLine(ctx, `const unsigned long ${callback.name}_debounce = ${callback.debounceMs};`);
             appendSourceLine(ctx, "");
         }
-        appendSourceLine(ctx, `${strategy.isrFunctionAttribute?.() ?? ""}${renderCallbackSignature(callback)} {`);
+        // IRAM_ATTR only on true ISR definitions. ESP-IDF's IRAM_ATTR uses
+        // __COUNTER__, so putting it on both forward decl and definition assigns
+        // conflicting .iram1.N sections (-Werror=attributes). Non-ISR callbacks
+        // (WiFi events, timers) must not be IRAM-placed either — they call printf.
+        const isrAttr = callback.isInterruptHandler ? (strategy.isrFunctionAttribute?.() ?? "") : "";
+        appendSourceLine(ctx, `${isrAttr}${renderCallbackSignature(callback)} {`);
         if (callback.debounceMs !== undefined && callback.debounceMs > 0) {
             appendSourceLine(ctx, `  volatile unsigned long now = ${strategy.currentTimeMillis()};`);
             appendSourceLine(ctx, `  if (now - ${callback.name}_lastTime < ${callback.name}_debounce) return;`);
@@ -141,10 +153,11 @@ export function emitCallbackFunctions(ctx) {
         appendSourceLine(ctx, "}");
         appendSourceLine(ctx, "");
     }
-    // Split-mode ISR callback forward declarations in header
+    // Split-mode ISR callback forward declarations in header (no IRAM_ATTR —
+    // attribute belongs on the definition only; see comment above).
     if (effectiveEmitMode === "split") {
         for (const callback of ctx.callbackFunctions) {
-            appendHeaderLine(ctx, `${strategy.isrFunctionAttribute?.() ?? ""}${renderCallbackSignature(callback)};`);
+            appendHeaderLine(ctx, `${renderCallbackSignature(callback)};`);
         }
     }
 }
@@ -172,6 +185,10 @@ export function emitFunctions(ctx) {
     // exported functions (which ride along with their definition below).
     for (let fi = 0; fi < mappedFunctions.length; fi++) {
         const fn = mappedFunctions[fi];
+        // Async functions become cooperative *Task state machines (emitAsyncTaskClasses).
+        // Emitting an empty stub here triggers -Wunused-function with no value.
+        if (fn.isAsync && ctx.hasAsyncRuntime)
+            continue;
         const declarationParameterList = ctx.statementRenderer.renderParameters(fn.parameters, true);
         const definitionParameterList = ctx.statementRenderer.renderParameters(fn.parameters, false);
         const readonlyPrefix = fn.isReadonlyReturnType ? "const " : "";
@@ -230,6 +247,29 @@ export function emitFunctions(ctx) {
             ctx.sourceMapEntries = ctx.headerMapEntries;
             ctx.headerMapEntries = _swapMaps;
         }
+        // Cooperative scheduler trampolines (Phase 0).
+        //
+        // When the strategy opts into priority/time-budget scheduling, the driver
+        // function's per-frame pumps are routed through the no-STL CoopSched. The
+        // trampolines (file-scope `static void __tc_coop_*(void*)`) must appear
+        // before the driver function definition so CoopSched can call them; they
+        // reference only global/static names (task instances, pump functions) so
+        // no captures are needed. Emitted once, ahead of the driver only.
+        const asyncDriverFnForTrampolines = strategy.asyncDriverFunctionName();
+        if (fn.name === asyncDriverFnForTrampolines &&
+            (hasPromiseRuntime || asyncTaskClasses.length > 0 || usesTimers)) {
+            const coopConfig = strategy.getAsyncRuntimeConfig();
+            if (coopConfig.enablePriority || coopConfig.enableTimeBudget) {
+                const coopUnits = buildDriverCoopUnits(asyncTaskClasses.map(t => t.taskVarName), hasPromiseRuntime, usesTimers);
+                if (coopUnits.length > 0) {
+                    const { trampolines } = buildCoopSchedInjection(coopUnits);
+                    appendSourceLine(ctx, "// ── CoopSched trampolines (priority/time-budget scheduling) ──");
+                    for (const t of trampolines)
+                        appendSourceLine(ctx, t);
+                    appendSourceLine(ctx, "");
+                }
+            }
+        }
         emitCommentLines(fn.leadingComments, "", (line) => appendSourceLine(ctx, line));
         if (fn.typeParameters && fn.typeParameters.length > 0) {
             appendSourceLine(ctx, `template<typename ${fn.typeParameters.join(", typename ")}>`);
@@ -246,64 +286,80 @@ export function emitFunctions(ctx) {
         if (hasPromiseRuntime && fn.name === asyncDriverFn) {
             appendSourceLine(ctx, "  cuttlefish_pump_microtasks();");
         }
-        if (fn.isAsync && ctx.hasAsyncRuntime) {
-            appendSourceLine(ctx, `  // driven as cooperative task in ${asyncDriverFn}()`);
+        if (fn.typeParameterConstraints) {
+            for (const [param, expr] of fn.typeParameterConstraints) {
+                appendSourceLine(ctx, `  static_assert(${expr}, "${param} constraint violated");`);
+            }
         }
-        else {
-            if (fn.typeParameterConstraints) {
-                for (const [param, expr] of fn.typeParameterConstraints) {
-                    appendSourceLine(ctx, `  static_assert(${expr}, "${param} constraint violated");`);
-                }
+        const functionScope = createChildEmissionScope(topLevelScope, fn.parameters);
+        ctx.cArrayVarNames = ctx.fnCArrayVarNames.get(String(fi)) ?? new Set();
+        const isLoopDriver = fn.name === asyncDriverFn;
+        const lastStmt = fn.statements.length > 0 ? fn.statements[fn.statements.length - 1] : null;
+        const lastIsReturn = lastStmt?.kind === "return";
+        const stmtsToEmit = (isLoopDriver && lastIsReturn)
+            ? fn.statements.slice(0, -1)
+            : fn.statements;
+        for (const statement of stmtsToEmit) {
+            appendRenderedStatement(ctx, statement, "  ", functionScope);
+        }
+        // Drive the UI runtime each frame. Fires only in the driver function when
+        // a UI is mounted (entryHasUI). Uses a separate gate from the async pump
+        // so a pure-UI program (no async/timers) still animates. When the strategy
+        // provides hostEventLoop, the per-frame work runs inside a while loop so a
+        // host target (SDL) can pump events and present between ticks. Emitted
+        // AFTER the function's init statements (ui_init/display_init/touch_init)
+        // so initialization precedes the loop.
+        if (entryHasUI() && fn.name === asyncDriverFn) {
+            const loop = strategy.hostEventLoop?.();
+            if (loop) {
+                appendSourceLine(ctx, `  bool ${loop.flagName} = true;`);
+                appendSourceLine(ctx, `  while (${loop.continueCondition}) {`);
+                appendSourceLine(ctx, `    ${loop.preIteration}`);
             }
-            const functionScope = createChildEmissionScope(topLevelScope, fn.parameters);
-            ctx.cArrayVarNames = ctx.fnCArrayVarNames.get(String(fi)) ?? new Set();
-            const isLoopDriver = fn.name === asyncDriverFn;
-            const lastStmt = fn.statements.length > 0 ? fn.statements[fn.statements.length - 1] : null;
-            const lastIsReturn = lastStmt?.kind === "return";
-            const stmtsToEmit = (isLoopDriver && lastIsReturn)
-                ? fn.statements.slice(0, -1)
-                : fn.statements;
-            for (const statement of stmtsToEmit) {
-                appendRenderedStatement(ctx, statement, "  ", functionScope);
+            appendSourceLine(ctx, `  uint32_t __tc_ui_now = static_cast<uint32_t>(${strategy.currentTimeMillis()});`);
+            appendSourceLine(ctx, "  static uint32_t __tc_ui_last_tick = __tc_ui_now;");
+            appendSourceLine(ctx, "  uint32_t __tc_ui_delta = __tc_ui_now - __tc_ui_last_tick;");
+            appendSourceLine(ctx, "  __tc_ui_last_tick = __tc_ui_now;");
+            appendSourceLine(ctx, "  if (__tc_ui_delta > 250) __tc_ui_delta = 250;");
+            appendSourceLine(ctx, "  ui_tick(static_cast<uint16_t>(__tc_ui_delta));");
+            if (loop) {
+                appendSourceLine(ctx, `    ${loop.postIteration}`);
+                appendSourceLine(ctx, `  }`);
             }
-            // Drive the UI runtime each frame. Fires only in the driver function when
-            // a UI is mounted (entryHasUI). Uses a separate gate from the async pump
-            // so a pure-UI program (no async/timers) still animates. When the strategy
-            // provides hostEventLoop, the per-frame work runs inside a while loop so a
-            // host target (SDL) can pump events and present between ticks. Emitted
-            // AFTER the function's init statements (ui_init/display_init/touch_init)
-            // so initialization precedes the loop.
-            if (entryHasUI() && fn.name === asyncDriverFn) {
-                const loop = strategy.hostEventLoop?.();
-                if (loop) {
-                    appendSourceLine(ctx, `  bool ${loop.flagName} = true;`);
-                    appendSourceLine(ctx, `  while (${loop.continueCondition}) {`);
-                    appendSourceLine(ctx, `    ${loop.preIteration}`);
+        }
+        if (isLoopDriver && (hasPromiseRuntime || asyncTaskClasses.length > 0 || usesTimers)) {
+            const taskNames = asyncTaskClasses.map(t => t.taskVarName);
+            const asyncConfig = strategy.getAsyncRuntimeConfig();
+            asyncConfig.hasPromiseRuntime = hasPromiseRuntime;
+            asyncConfig.hasTimers = usesTimers;
+            // Cooperative scheduler path (Phase 0): when opted in, replace the flat
+            // per-frame pump sequence with a single CoopSched dispatch. The work
+            // units mirror exactly what the strategy's asyncLoopInjection() would
+            // have emitted (so Zephyr, which omits the microtask pump, still omits
+            // it), but they are dispatched in priority order and budget-bounded.
+            if (asyncConfig.enablePriority || asyncConfig.enableTimeBudget) {
+                const coopUnits = buildDriverCoopUnits(taskNames, hasPromiseRuntime, usesTimers);
+                if (coopUnits.length > 0) {
+                    const { injection } = buildCoopSchedInjection(coopUnits);
+                    for (const line of injection)
+                        appendSourceLine(ctx, line);
                 }
-                appendSourceLine(ctx, `  uint32_t __tc_ui_now = (uint32_t)${strategy.currentTimeMillis()};`);
-                appendSourceLine(ctx, "  static uint32_t __tc_ui_last_tick = __tc_ui_now;");
-                appendSourceLine(ctx, "  uint32_t __tc_ui_delta = __tc_ui_now - __tc_ui_last_tick;");
-                appendSourceLine(ctx, "  __tc_ui_last_tick = __tc_ui_now;");
-                appendSourceLine(ctx, "  if (__tc_ui_delta > 250) __tc_ui_delta = 250;");
-                appendSourceLine(ctx, "  ui_tick((uint16_t)__tc_ui_delta);");
-                if (loop) {
-                    appendSourceLine(ctx, `    ${loop.postIteration}`);
-                    appendSourceLine(ctx, `  }`);
+                else {
+                    // No work units: fall back to the strategy's own injection.
+                    const injectionLines = strategy.asyncLoopInjection(taskNames, asyncConfig);
+                    for (const line of injectionLines)
+                        appendSourceLine(ctx, `  ${line}`);
                 }
             }
-            if (isLoopDriver && (hasPromiseRuntime || asyncTaskClasses.length > 0 || usesTimers)) {
-                const taskNames = asyncTaskClasses.map(t => t.taskVarName);
-                const asyncConfig = strategy.getAsyncRuntimeConfig();
-                asyncConfig.hasPromiseRuntime = hasPromiseRuntime;
-                asyncConfig.hasTimers = usesTimers;
+            else {
                 const injectionLines = strategy.asyncLoopInjection(taskNames, asyncConfig);
                 for (const line of injectionLines) {
                     appendSourceLine(ctx, `  ${line}`);
                 }
             }
-            if (isLoopDriver && lastIsReturn) {
-                appendRenderedStatement(ctx, lastStmt, "  ", functionScope);
-            }
+        }
+        if (isLoopDriver && lastIsReturn) {
+            appendRenderedStatement(ctx, lastStmt, "  ", functionScope);
         }
         appendSourceLine(ctx, "}");
         emitCommentLines(fn.trailingComments, "", (line) => appendSourceLine(ctx, line));
@@ -338,16 +394,21 @@ export function emitFunctions(ctx) {
 export function emitFunctionForwardDeclarations(ctx) {
     const { strategy, effectiveEmitMode } = ctx;
     const excludedNames = new Set(strategy.forwardDeclarationExclusions?.() ?? []);
-    // ISR callback forward declarations.
+    // Callback forward declarations (no IRAM_ATTR — ESP-IDF's attribute uses
+    // __COUNTER__, so decl+def would get conflicting .iram1.N sections).
     if (effectiveEmitMode !== "split") {
         for (const callback of ctx.callbackFunctions) {
-            appendSourceLine(ctx, `${strategy.isrFunctionAttribute?.() ?? ""}${renderCallbackSignature(callback)};`);
+            appendSourceLine(ctx, `${renderCallbackSignature(callback)};`);
         }
     }
     let emittedAnyFn = false;
     for (const fn of ctx.mappedFunctions) {
         if (excludedNames.has(fn.name))
             continue;
+        // Async functions become *Task classes; calls lower to `fooTask.run()`.
+        // Forward-declaring empty stubs triggers -Wunused-function.
+        if (fn.isAsync && ctx.hasAsyncRuntime)
+            continue;
         const isExported = fn.isExported === true;
         // A function is an entrypoint if it is the strategy's primary entrypoint
         // (e.g. `setup` on Arduino, `main` on native) OR one of the platform's
@@ -426,3 +487,42 @@ export function emitFunctionForwardDeclarations(ctx) {
         appendSourceLine(ctx, "");
     }
 }
+/**
+ * Build the CoopSched work units for the driver function's per-frame pumps.
+ *
+ * The units mirror what a strategy's asyncLoopInjection() emits as a flat
+ * sequence, so the cooperative scheduler preserves each strategy's decisions
+ * about WHICH pumps run (e.g. Zephyr omits the std::function microtask pump
+ * because its async path is state-machine-based). Default priorities:
+ *   - async task .run()        → priority 1 (latency-sensitive: drives awaits)
+ *   - microtask pump           → priority 1 (continuations of resolved promises)
+ *   - cooperative timer pump   → priority 0 (less latency-critical)
+ * Both are tunable via AsyncRuntimeConfig.schedulerPriorities; the scheduler
+ * bucket-walks from the highest level down to 0.
+ */
+function buildDriverCoopUnits(taskVarNames, hasPromiseRuntime, hasTimers) {
+    const units = [];
+    let taskIdx = 0;
+    for (const name of taskVarNames) {
+        units.push({
+            name: `task_${taskIdx++}`,
+            body: `${name}.run();`,
+            priority: 1,
+        });
+    }
+    if (hasPromiseRuntime) {
+        units.push({
+            name: "microtasks",
+            body: "cuttlefish_pump_microtasks();",
+            priority: 1,
+        });
+    }
+    if (hasTimers) {
+        units.push({
+            name: "timers",
+            body: "__tc_timer_runtime.run();",
+            priority: 0,
+        });
+    }
+    return units;
+}

package/dist/emit/emitters/line-appender.js

@@ -1,7 +1,17 @@
 import { cloneEmissionScopeState, recordVariableType } from "../snprintf-helpers.js";
 import { emitCommentLines } from "../utils/index.js";
 import { escapeCppKeyword } from "../../utils/strings.js";
+import { formatLinemarker, shouldEmitMarker, sourceKey } from "./line-marker.js";
 export function appendSourceLine(ctx, line, entry) {
+    // GDB debug mode: emit a linemarker before lines whose source span transitions.
+    // Runs only when an entry is present (raw braces/whitespace carry no span).
+    if (ctx.debugMode === 'gdb' && entry) {
+        const next = sourceKey(entry.tsSpan);
+        if (shouldEmitMarker(ctx.lastEmittedSource, next)) {
+            ctx.sourceLines.push(formatLinemarker(entry.tsSpan.filePath, entry.tsSpan.startLine));
+        }
+        ctx.lastEmittedSource = next;
+    }
     ctx.sourceLines.push(line);
     if (!entry)
         return;
@@ -17,6 +27,15 @@ export function appendSourceLine(ctx, line, entry) {
     });
 }
 export function appendHeaderLine(ctx, line, entry) {
+    // GDB debug mode: same transition logic as appendSourceLine, against the
+    // shared lastEmittedSource slot. See line-marker.ts for rationale.
+    if (ctx.debugMode === 'gdb' && entry) {
+        const next = sourceKey(entry.tsSpan);
+        if (shouldEmitMarker(ctx.lastEmittedSource, next)) {
+            ctx.headerLines.push(formatLinemarker(entry.tsSpan.filePath, entry.tsSpan.startLine));
+        }
+        ctx.lastEmittedSource = next;
+    }
     ctx.headerLines.push(line);
     if (!entry)
         return;

package/dist/emit/emitters/line-marker.d.ts

@@ -0,0 +1,38 @@
+import type { SourceSpan } from '../../types.js';
+/**
+ * A previously-emitted source location, used for transition detection so we
+ * emit a linemarker only when the source file or line actually changes.
+ */
+export interface EmittedSource {
+    filePath: string;
+    /** 0-based source line (matches SourceSpan.startLine). */
+    line: number;
+}
+/**
+ * Format a GCC linemarker for the given path and 0-based source line.
+ * Output form: `# <line+1> "<path>"`.
+ *
+ * The path is normalized to forward slashes (Windows backslashes break GDB
+ * source resolution from the ESP-IDF build directory) and resolved to an
+ * absolute path so GDB finds the .ts file regardless of its cwd.
+ *
+ * GCC accepts both `#line N "F"` and the linemarker form `# N "F"`; we use
+ * the latter because it's what GCC emits in preprocessed output and it flows
+ * cleanly into DWARF.
+ */
+export declare function formatLinemarker(filePath: string, line: number): string;
+/**
+ * Decide whether a linemarker should be emitted before the next source line,
+ * given the previously-emitted marker (or null for the first one).
+ *
+ * Returns true only on file or line transition — this keeps the emitted C++
+ * clean (one marker per source-span change, not per emitted C++ line, which
+ * would be noisy and slow).
+ */
+export declare function shouldEmitMarker(prev: EmittedSource | null, next: EmittedSource): boolean;
+/**
+ * Extract the {filePath, line} for transition tracking from a SourceSpan.
+ * SourceSpan.startLine is 0-based; kept 0-based here so shouldEmitMarker
+ * compares apples to apples (formatLinemarker does the +1 at format time).
+ */
+export declare function sourceKey(span: SourceSpan): EmittedSource;

package/dist/emit/emitters/line-marker.js

@@ -0,0 +1,39 @@
+import { resolve } from 'node:path';
+/**
+ * Format a GCC linemarker for the given path and 0-based source line.
+ * Output form: `# <line+1> "<path>"`.
+ *
+ * The path is normalized to forward slashes (Windows backslashes break GDB
+ * source resolution from the ESP-IDF build directory) and resolved to an
+ * absolute path so GDB finds the .ts file regardless of its cwd.
+ *
+ * GCC accepts both `#line N "F"` and the linemarker form `# N "F"`; we use
+ * the latter because it's what GCC emits in preprocessed output and it flows
+ * cleanly into DWARF.
+ */
+export function formatLinemarker(filePath, line) {
+    const absolute = resolve(filePath);
+    const normalized = absolute.split(/[\\/]/).join('/');
+    return `# ${line + 1} "${normalized}"`;
+}
+/**
+ * Decide whether a linemarker should be emitted before the next source line,
+ * given the previously-emitted marker (or null for the first one).
+ *
+ * Returns true only on file or line transition — this keeps the emitted C++
+ * clean (one marker per source-span change, not per emitted C++ line, which
+ * would be noisy and slow).
+ */
+export function shouldEmitMarker(prev, next) {
+    if (prev === null)
+        return true;
+    return prev.filePath !== next.filePath || prev.line !== next.line;
+}
+/**
+ * Extract the {filePath, line} for transition tracking from a SourceSpan.
+ * SourceSpan.startLine is 0-based; kept 0-based here so shouldEmitMarker
+ * compares apples to apples (formatLinemarker does the +1 at format time).
+ */
+export function sourceKey(span) {
+    return { filePath: span.filePath, line: span.startLine };
+}

package/dist/emit/emitters/output-finalizer.d.ts

@@ -1,4 +1,10 @@
 import type { GeneratedOutputs } from "../../types.js";
 import type { EmitterContext } from "./emitter-context.js";
 export declare function emitPreamble(ctx: EmitterContext): void;
+/**
+ * Emit cooperative async state-machine classes. Must run AFTER top-level
+ * globals (emitTypeDeclarations) so identifiers like WIFI_SSID referenced
+ * from task bodies are already declared.
+ */
+export declare function emitAsyncTaskClasses(ctx: EmitterContext): void;
 export declare function finalizeOutput(ctx: EmitterContext): GeneratedOutputs;

package/dist/emit/emitters/output-finalizer.js

@@ -1,8 +1,11 @@
 import path from "node:path";
-import { writeText } from "../../utils/fs.js";
+import { writeText, readText } from "../../utils/fs.js";
 import { makeGeneratedMap, writeSourceMap } from "../../mapping/source-map.js";
 import { dedupe, hasConsoleCalls, resolveTranspiledModuleInclude } from "../utils/index.js";
 import { appendHeaderLine } from "./line-appender.js";
+import { runSelfCheck } from "../compliance/rule-engine.js";
+import { renderRegistryJson } from "../compliance/deviation-writer.js";
+import { renderArxml } from "../compliance/arxml-writer.js";
 /** Derives a unique C preprocessor guard name from a source file path. */
 function sanitizeGuardName(filePath) {
     // Use the basename minus extension, uppercased, with non-alphanumeric
@@ -26,7 +29,7 @@ function polyfillDefinitionGuard(definition) {
     return null;
 }
 export function emitPreamble(ctx) {
-    const { strategy, effectiveEmitMode, program, shimLines, emittedPolyfills, asyncTaskClasses, includes, programAnalysis } = ctx;
+    const { strategy, effectiveEmitMode, program, shimLines, emittedPolyfills, includes, programAnalysis } = ctx;
     for (const include of dedupe(includes)) {
         appendSourceLineLocal(ctx, `#include ${include}`);
     }
@@ -73,16 +76,8 @@ export function emitPreamble(ctx) {
         }
         appendSourceLineLocal(ctx, "");
     }
-    if (asyncTaskClasses.length > 0) {
-        for (const { classDef, instanceDecl } of asyncTaskClasses) {
-            for (const line of classDef.split("\n")) {
-                appendSourceLineLocal(ctx, line);
-            }
-            appendSourceLineLocal(ctx, "");
-            appendSourceLineLocal(ctx, instanceDecl);
-            appendSourceLineLocal(ctx, "");
-        }
-    }
+    // Async task classes are emitted later (emitAsyncTaskClasses) AFTER top-level
+    // globals so references like WIFI_SSID inside the state machine compile.
     if (strategy.needsVectorOverload() && hasConsoleCalls(program, strategy) && (programAnalysis.usesVectorTypes || programAnalysis.hasArrayInObjectLiteral)) {
         appendSourceLineLocal(ctx, "template <typename T>");
         appendSourceLineLocal(ctx, "std::ostream& operator<<(std::ostream& os, const std::vector<T>& values)");
@@ -136,6 +131,24 @@ export function emitPreamble(ctx) {
         appendSourceLineLocal(ctx, "");
     }
 }
+/**
+ * Emit cooperative async state-machine classes. Must run AFTER top-level
+ * globals (emitTypeDeclarations) so identifiers like WIFI_SSID referenced
+ * from task bodies are already declared.
+ */
+export function emitAsyncTaskClasses(ctx) {
+    const { asyncTaskClasses } = ctx;
+    if (asyncTaskClasses.length === 0)
+        return;
+    for (const { classDef, instanceDecl } of asyncTaskClasses) {
+        for (const line of classDef.split("\n")) {
+            appendSourceLineLocal(ctx, line);
+        }
+        appendSourceLineLocal(ctx, "");
+        appendSourceLineLocal(ctx, instanceDecl);
+        appendSourceLineLocal(ctx, "");
+    }
+}
 export function finalizeOutput(ctx) {
     const { program, strategy, options, effectiveEmitMode, isNpmPackage, baseName, includes, shimLines, emittedPolyfills } = ctx;
     const outDir = options.outDir;
@@ -252,6 +265,82 @@ export function finalizeOutput(ctx) {
         : undefined;
     const diagnostics = [...program.diagnostics, ...ctx.profileDiagnostics, ...ctx.emitDiagnostics];
     diagnostics.push(...strategy.emitDiagnostics(options.emitMode));
+    // ── AUTOSAR compliance self-check + sidecar ────────────────────────────
+    // Runs only when --autosar is warn or strict. Emits an AUTOSAR_<ruleId>
+    // diagnostic per finding (severity: error for required unrecorded
+    // violations in strict mode, otherwise warning) and writes the sidecar
+    // deviation registry next to the emitted artifact.
+    if (ctx.compliance.isEnabled()) {
+        // Scan the ACTUAL file content (post-writeText) rather than ctx.sourceLines,
+        // because some ctx.sourceLines entries contain embedded newlines (e.g. ESP32
+        // shim blocks pushed as multi-line strings), making array indices != file
+        // line numbers. Reading the written file gives correct 1:1 line numbers.
+        const actualSourceLines = outputHeaderPath
+            ? readText(sourcePath).split("\n")
+            : readText(sourcePath).split("\n");
+        const actualHeaderLines = outputHeaderPath
+            ? readText(outputHeaderPath).split("\n")
+            : [];
+        const findings = runSelfCheck(ctx.compliance, actualSourceLines, actualHeaderLines);
+        const mode = ctx.compliance.mode();
+        // Helper: map a C++ generated line back to its originating TS source
+        // line via the source map, so diagnostics point at the user's code.
+        const mapCppLineToTs = (cppLine) => {
+            // Find the source-map entry whose generated range covers cppLine.
+            // Entries are ordered by generatedStartLine; find the last one whose
+            // start is ≤ cppLine.
+            let best = null;
+            for (const entry of ctx.sourceMapEntries) {
+                if (entry.generatedStartLine <= cppLine) {
+                    if (!best || entry.generatedStartLine > best.generatedStartLine) {
+                        best = entry;
+                    }
+                }
+            }
+            if (best) {
+                return { filePath: best.tsSpan.filePath, line: best.tsSpan.startLine };
+            }
+            return null;
+        };
+        for (const f of findings) {
+            const isError = mode === "strict" &&
+                f.kind === "unrecorded-violation" &&
+                f.severity === "required";
+            // Map the C++ line back to TS so the diagnostic points at user code.
+            const tsLoc = mapCppLineToTs(f.line);
+            const emittedFile = f.file === "header" ? `${baseName}.h` : path.basename(sourcePath);
+            const cppRef = `${emittedFile}:${f.line}`;
+            const tsRef = tsLoc ? `${path.basename(tsLoc.filePath)}:${tsLoc.line}` : null;
+            const locationDesc = tsRef
+                ? `${tsRef} (emitted at ${cppRef})`
+                : cppRef;
+            const diag = {
+                severity: isError ? "error" : "warning",
+                code: `AUTOSAR_${f.ruleId}`,
+                message: `AUTOSAR ${f.ruleId} ${f.kind} at ${locationDesc}: ${f.snippet}`,
+                // Point the diagnostic at the TS source line (if mapped) so the
+                // CLI's file:line:col display is meaningful to the user. If the
+                // violation is in framework/runtime shim code with no TS origin,
+                // point at the emitted C++ artifact instead.
+                filePath: tsLoc?.filePath ?? sourcePath,
+                line: tsLoc?.line ?? f.line,
+                column: 1,
+            };
+            diagnostics.push(diag);
+        }
+        // Sidecar deviation registry — written for both warn and strict modes
+        // alongside the emitted artifact (mirrors how .thcppmap.json sits next
+        // to the .cpp/.ino today).
+        const toolVersion = options.toolVersion ?? "unknown";
+        const registryPath = path.join(outDir, `${baseName}.autosar-deviations.json`);
+        writeText(registryPath, renderRegistryJson(ctx.compliance, path.basename(sourcePath), toolVersion));
+        // Optional ARXML projection (Artop/DaVinci tooling). Gated behind
+        // --autosar-arxml so projects that don't need it pay no cost.
+        if (options.autosarArxml) {
+            const arxmlPath = path.join(outDir, `${baseName}.autosar-deviations.arxml`);
+            writeText(arxmlPath, renderArxml(ctx.compliance, path.basename(sourcePath)));
+        }
+    }
     return {
         headerPath: outputHeaderPath,
         sourcePath,

package/dist/emit/emitters/setup.d.ts

@@ -1,3 +1,20 @@
 import type { ProgramIR } from "../../api/index.js";
 import type { EmitterContext, EmitterOptions } from "./emitter-context.js";
+/**
+ * Detect whether a program uses @typecad/safety. The safety transform pass
+ * injects safety.* ops when in use; strategies consult this to decide
+ * whether to emit the __tc_gpio_read shim that the safety voter calls.
+ * Mirrors programUsesWdt() above (same inline walker pattern).
+ *
+ * `hal-expr` (the expression-position safety.read_safe lowering produced
+ * by `const r = safe.read(pin)`) lives in expression trees, not at statement
+ * level — but it's carried inside a var_decl statement whose initializer is
+ * the hal-expr, and the var_decl gets visited as a top-level statement. We
+ * detect both: statement-level `hal-op` operations, and any statement whose
+ * rendered initializer text mentions safety.* (a defensive catch for the
+ * hal-expr-in-initializer case). The latter is rarely needed because the
+ * voter's read_safe op is also captured at the call site, but kept for
+ * robustness.
+ */
+export declare function programUsesSafety(program: ProgramIR): boolean;
 export declare function buildEmitterContext(program: ProgramIR, options: EmitterOptions): EmitterContext;