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

package/dist/ir/transformers/variables.js

@@ -11,6 +11,7 @@ import { isKnownHALClass, getCtorIncludes, getHALCtorFieldMap, registerFloatVari
 import { httpFactoryVerb, httpUrlArgText } from "../hal/hal-parser.js";
 import { resolveHALCallForVarInit } from "./hal-call-resolver.js";
 import { recordSignal } from "./ui-call-resolver.js";
+import { hasSafetyHook, requireSafetyHook } from "../../safety-hook.js";
 function replaceHalReadBufferPlaceholder(op, varName) {
     if (op.operation === "i2c.read_buffer" && op.buffer === "__HAL_READ_BUF__") {
         return { ...op, buffer: varName };
@@ -375,6 +376,56 @@ export function variableStatementToIR(statement, fileName, sourceText, diagnosti
                 localVariableTypes.set(varName, cppType);
                 continue;
             }
+            // ── safe.<method>(...) — @typecad/safety call as initializer.
+            // Handles expression-position safe.* calls like `const r = safe.read(pin)`.
+            // The statement-position form (safe.pinMode(...)) is handled in the
+            // call-statement transformer. Both produce hal-op IR nodes that
+            // routeHALOp() later dispatches to the safety hook.
+            if (hasSafetyHook() &&
+                ts.isCallExpression(declaration.initializer) &&
+                ts.isPropertyAccessExpression(declaration.initializer.expression) &&
+                ts.isIdentifier(declaration.initializer.expression.expression) &&
+                declaration.initializer.expression.expression.text === "safe") {
+                const method = declaration.initializer.expression.name.text;
+                const argValues = declaration.initializer.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)) {
+                        const name = a.text;
+                        if (name === "INPUT")
+                            return 0;
+                        if (name === "OUTPUT")
+                            return 1;
+                        if (name === "INPUT_PULLUP")
+                            return 2;
+                        return name;
+                    }
+                    return undefined;
+                });
+                const op = requireSafetyHook().resolveSemanticCall?.(`safe.${method}`, argValues);
+                if (op) {
+                    // Emit a var_decl initialized by a hal-expr carrying the safety op.
+                    // routeHALOp() resolves it to the C++ expression at emit time.
+                    const initExpr = { kind: "hal-expr", operation: op };
+                    lowered.push({
+                        kind: "var_decl",
+                        name: varName,
+                        storage,
+                        cppType: "auto",
+                        initializer: initExpr,
+                        sourceSpan: makeSourceSpan(declaration, fileName, sourceText),
+                    });
+                    // auto-deduced to SafeReadResult on the C++ side.
+                    localVariableTypes.set(varName, "auto");
+                    continue;
+                }
+            }
             if (ts.isNewExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression)) {
                 const className = declaration.initializer.expression.text;
                 const ctorArgs = declaration.initializer.arguments;

package/dist/ir/type-resolution.js

@@ -48,6 +48,14 @@ const BOARD_CONSTANT_TYPE_NAMES = new Set([
 const OWNERSHIP_WRAPPER_TYPE_NAMES = new Set([
     "Owned", "Shared", "Mutable",
 ]);
+/** Safety wrapper types: like ownership wrappers (phantom TS types that carry
+ *  a type parameter), but instead of stripping the wrapper, the C++ keeps it
+ *  as a template instantiation: SafeVariable<number> → SafeVariable<int32_t>.
+ *  The C++ template definition is provided by the safety polyfill. */
+const SAFE_WRAPPER_TYPE_NAMES = new Set([
+    "SafeVariable",
+    "SafeInt",
+]);
 export function resolveAliasedTypeNode(node, typeAliases, visited = new Set()) {
     if (!node || !typeAliases) {
         return node;
@@ -147,6 +155,16 @@ export function typeNodeToCppType(node, typeAliases, typeParametersInScope) {
             const innerTypeNode = node.typeArguments?.[0];
             return typeNodeToCppType(innerTypeNode, typeAliases, typeParametersInScope);
         }
+        // SafeVariable<T> is a safety wrapper: unlike ownership wrappers (which
+        // strip the wrapper name entirely), SafeVariable keeps the wrapper name
+        // in the C++ type because the polyfill provides a template definition.
+        // SafeVariable<number> → SafeVariable<int> (the template is emitted by
+        // the safety polyfill's helperStructs).
+        if (SAFE_WRAPPER_TYPE_NAMES.has(wrapperName)) {
+            const innerTypeNode = node.typeArguments?.[0];
+            const innerCppType = typeNodeToCppType(innerTypeNode, typeAliases, typeParametersInScope);
+            return `${wrapperName}<${innerCppType}>`;
+        }
     }
     const resolvedNode = resolveAliasedTypeNode(node, typeAliases) ?? node;
     // If the resolved node is an object literal type (e.g. type X = { a: number }),

package/dist/ir/ui-element-auto-wire.js

@@ -81,7 +81,7 @@ function autoWireNode(treeName, node, nodeIndex) {
                 nodeIndex,
                 property: "text",
                 fnName: `__ui_bindtext_${nodeIndex}`,
-                cppBody: `snprintf(buf, size, "%s", ${sig});`,
+                cppBody: `snprintf(buf, static_cast<size_t>(size), "%s", ${sig});`,
             });
             // Write: keyboard commit → signal.set(text).
             recordInputBinding({
@@ -156,13 +156,15 @@ function autoWireNode(treeName, node, nodeIndex) {
             fnName: `__ui_${node.id}_autoclick`,
             callbackBody: `__ui_nodes[${nodeIndex}].value = (__ui_nodes[${nodeIndex}].value + 1) % ${count};`,
         });
-        // Auto-bind text to show the current option via snprintf if/else chain
+        // Auto-bind text to show the current option via snprintf if/else chain.
+        // Cast size to size_t to satisfy -Wformat (snprintf's n param is size_t;
+        // the textFn signature uses uint8_t).
         const branches = options.map((opt, i) => {
             if (i === 0)
-                return `if (__ui_nodes[${nodeIndex}].value == 0) { snprintf(buf, size, "%s", "${opt}"); }`;
-            return `else if (__ui_nodes[${nodeIndex}].value == ${i}) { snprintf(buf, size, "%s", "${opt}"); }`;
+                return `if (__ui_nodes[${nodeIndex}].value == 0) { snprintf(buf, static_cast<size_t>(size), "%s", "${opt}"); }`;
+            return `else if (__ui_nodes[${nodeIndex}].value == ${i}) { snprintf(buf, static_cast<size_t>(size), "%s", "${opt}"); }`;
         }).join(" ");
-        const elseBranch = `else { snprintf(buf, size, "%s", "${options[0] || ""}"); }`;
+        const elseBranch = `else { snprintf(buf, static_cast<size_t>(size), "%s", "${options[0] || ""}"); }`;
         recordBinding({
             nodeIndex,
             property: "text",

package/dist/ir/utils/map-statements.d.ts

@@ -0,0 +1,4 @@
+import type { ProgramIR, StatementIR } from "../../api/shared/index.js";
+/** Map each statement in the program to zero or more statements. The result
+ *  is a new ProgramIR; the input is not modified. */
+export declare function mapProgramStatements(program: ProgramIR, fn: (stmt: StatementIR) => StatementIR[]): ProgramIR;

package/dist/ir/utils/map-statements.js

@@ -0,0 +1,79 @@
+// ---------------------------------------------------------------------------
+// mapProgramStatements — produce a NEW ProgramIR with statements mapped by fn.
+//
+// The existing walkers in walk-ir.ts are read-only; filterProgramIR
+// (ir/filter.ts) produces a new IR but only filters, never injects. This
+// helper extends the "produce-new-IR" idiom to "map each statement to N
+// statements," which is what the safety pinMode-intercept pass needs to
+// inject companion ops.
+//
+// Non-mutating: every statement container is rebuilt; the input program is
+// untouched. The shape mirrors walkProgramIR's enumeration of containers
+// (walk-ir.ts:107-134): topLevelStatements, functions, classes
+// (constructor/methods/getters/setters), namespaces (recursively).
+//
+// KNOWN LIMITATION (Part A scope): does NOT recurse into nested statement
+// bodies (if/for/while/switch/cases). Statements at the top level of a
+// function body, class method, namespace function, or the file's top level
+// ARE mapped. pinMode calls inside `if (...) { pinMode(...); }` are not. The
+// safety package's design (docs/superpowers/specs/2026-07-27-safety-package-
+// part-a-design.md) explicitly bounds Part A to this. A future iteration can
+// thread mapping into nested bodies by recursing into thenBranch/elseBranch/
+// body/initializer/increment/cases — see walkNestedStatements (walk-ir.ts:3).
+// ---------------------------------------------------------------------------
+/** Map each statement in the program to zero or more statements. The result
+ *  is a new ProgramIR; the input is not modified. */
+export function mapProgramStatements(program, fn) {
+    const mapList = (stmts) => {
+        const out = [];
+        for (const s of stmts) {
+            const mapped = fn(s);
+            for (const m of mapped)
+                out.push(m);
+        }
+        return out;
+    };
+    const newFunctions = program.functions.map((f) => ({
+        ...f,
+        statements: mapList(f.statements),
+    }));
+    const newClasses = program.classes.map((cls) => ({
+        ...cls,
+        constructor: cls.constructor
+            ? { ...cls.constructor, statements: mapList(cls.constructor.statements) }
+            : cls.constructor,
+        methods: cls.methods.map((m) => ({ ...m, statements: mapList(m.statements) })),
+        getters: cls.getters.map((g) => ({ ...g, statements: mapList(g.statements) })),
+        setters: cls.setters.map((s) => ({ ...s, statements: mapList(s.statements) })),
+    }));
+    const newNamespaces = program.namespaces.map((ns) => mapNamespace(ns, fn));
+    return {
+        ...program,
+        topLevelStatements: mapList(program.topLevelStatements),
+        functions: newFunctions,
+        classes: newClasses,
+        namespaces: newNamespaces,
+    };
+}
+function mapNamespace(ns, fn) {
+    const mapList = (stmts) => {
+        const out = [];
+        for (const s of stmts)
+            out.push(...fn(s));
+        return out;
+    };
+    return {
+        ...ns,
+        functions: ns.functions.map((f) => ({ ...f, statements: mapList(f.statements) })),
+        classes: ns.classes.map((cls) => ({
+            ...cls,
+            constructor: cls.constructor
+                ? { ...cls.constructor, statements: mapList(cls.constructor.statements) }
+                : cls.constructor,
+            methods: cls.methods.map((m) => ({ ...m, statements: mapList(m.statements) })),
+            getters: cls.getters.map((g) => ({ ...g, statements: mapList(g.statements) })),
+            setters: cls.setters.map((s) => ({ ...s, statements: mapList(s.statements) })),
+        })),
+        children: ns.children ? ns.children.map((c) => mapNamespace(c, fn)) : ns.children,
+    };
+}

package/dist/ir/validation-orchestrator.js

@@ -1,6 +1,7 @@
 import { resolveStrategy } from "../platform/registry.js";
 import { hasLoadedFramework, getLoadedFramework } from "../framework-registry.js";
 import { analyzeInterruptSafety, inferVolatileForIsrSharedVars, detectReentrancyRisk } from "./interrupt-analysis.js";
+import { analyzeWorkerIsolation } from "./worker-analysis.js";
 import { validateADCRange } from "./adc-range-validation.js";
 import { createEmptyPeripheralUsage } from "./peripheral-usage.js";
 import { validatePeripherals } from "./peripheral-validation.js";
@@ -31,9 +32,13 @@ export function runProgramValidations(program, strategy) {
     diagnostics.push(...validatePWMTimerSharing(peripheralUsage, program.boardConstants, program.fileName));
     diagnostics.push(...validateTimer0PWMTimingConflict(peripheralUsage, program.boardConstants, program.fileName));
     diagnostics.push(...validatePulldownSupport(peripheralUsage, program.boardConstants, program.fileName));
-    diagnostics.push(...analyzeInterruptSafety(program, peripheralUsage));
+    diagnostics.push(...analyzeInterruptSafety(program, peripheralUsage, resolvedStrategy.isrUnsafeOperations?.()));
     inferVolatileForIsrSharedVars(program, diagnostics);
     detectReentrancyRisk(program, diagnostics);
+    // Worker isolation: bus access in workers is a hard error; worker-shared
+    // globals get volatile promotion (info) or a data-race warning. Only fires
+    // when worker.submit ops are present, so non-worker programs are unaffected.
+    analyzeWorkerIsolation(program, diagnostics);
     diagnostics.push(...validateADCRange(program, program.boardConstants));
     diagnostics.push(...validateUnitSuspicion(program));
     diagnostics.push(...validatePinModeConfig(program));

package/dist/ir/worker-analysis.d.ts

@@ -0,0 +1,10 @@
+import type { ProgramIR } from '../api/index.js';
+import type { Diagnostic } from '../types.js';
+/**
+ * Analyze worker isolation: (a) promote volatile for worker-shared globals,
+ * (b) flag shared-mutable globals, (c) hard-error on bus access in workers.
+ *
+ * Mutates the IR for (a) (sets isVolatile=true on qualifying var_decls) and
+ * pushes diagnostics for all three tiers. Returns the diagnostics it added.
+ */
+export declare function analyzeWorkerIsolation(program: ProgramIR, diagnostics: Diagnostic[]): Diagnostic[];

package/dist/ir/worker-analysis.js

@@ -0,0 +1,261 @@
+// ---------------------------------------------------------------------------
+// Worker Isolation Analysis (Phase 1/2)
+//
+// Models the safety property of the generalized worker-offload feature: worker
+// functions run on a separate thread of control (a FreeRTOS task / Zephyr
+// workqueue thread), so any shared mutable state between a worker and the main
+// loop() is a real data race that the cooperative model otherwise eliminates.
+//
+// This pass mirrors interrupt-analysis.ts but splits the verdict by the surface
+// a worker shares with main:
+//
+//   (a) Shared GLOBALS — the worker writes a global the main loop reads (or
+//       both write it). The worker can run on a different core, so:
+//         - worker-written + main-read  → promote to volatile + info diagnostic
+//           (mirrors the ISR volatile pass; the barrier contract makes the
+//           write visible, volatile stops the compiler caching the read).
+//         - worker-written + main-written (mutated by both) → warning:
+//           a true data race the barrier alone cannot fix.
+//
+//   (b) Shared BUSES (I2C/SPI/UART/Wire/Serial) — a worker touching a bus is a
+//       HARD ERROR in v1. Rationale: the existing take()/release() bus-ownership
+//       mechanism is statically enforced (peripheral-ownership.ts) but runtime-
+//       UNIMPLEMENTED (take() is a no-op). A bus is a protocol-level conflict
+//       (two masters on the wire), so leaning on a lock that isn't there would
+//       be unsound. Workers are compute/pure-only in v1. When the take/release
+//       runtime backend lands (the named follow-on), this tier flips from
+//       error → allowed-by-take/release.
+//
+// Worker function identification: a worker function is one referenced by a
+// worker.submit HAL op (expr.operation.operation === 'worker.submit'). The op
+// carries fnRef (the C++ symbol), which we correlate to a program function by
+// name. This mirrors how interrupt-analysis identifies ISRs via
+// isInterruptHandler, but resolves through the HAL op instead of a callback
+// flag (worker functions are plain functions, not callbacks).
+// ---------------------------------------------------------------------------
+import { collectAssignedNames, collectReadNames } from './interrupt-analysis.js';
+import { walkProgramIR } from './utils/walk-ir.js';
+// Bus-object prefixes a worker is forbidden from touching in v1. Mirrors the
+// getBusName regex in peripheral-ownership.ts (I2C/SPI/UART/Wire/Serial).
+const BUS_PREFIXES = ['I2C', 'SPI', 'UART', 'Wire', 'Serial'];
+/** True if an identifier/callee string names a bus object (forbidden in workers). */
+function isBusName(name) {
+    // Wire / Serial exactly, or I2C<n> / SPI<n> / UART<n> / Serial<n>.
+    if (name === 'Wire' || name === 'Serial')
+        return true;
+    for (const p of ['I2C', 'SPI', 'UART']) {
+        if (new RegExp(`^${p}\\d`).test(name))
+            return true;
+    }
+    if (/^Serial\d/.test(name))
+        return true;
+    return false;
+}
+/**
+ * Walk every expression in the program, invoking the visitor for worker.submit
+ * HAL ops. HAL ops appear as expressions whose `.operation.operation` is the
+ * op-kind string (mirrors the scan in program-analysis.ts:348).
+ */
+function scanForWorkerSubmitOps(program, visit) {
+    walkProgramIR(program, (stmt) => {
+        walkExpressionsInStatementLocal(stmt, (expr) => {
+            if (expr && typeof expr === 'object'
+                && expr.operation && typeof expr.operation === 'object'
+                && expr.operation.operation === 'worker.submit') {
+                const fnRef = expr.operation.fnRef;
+                if (typeof fnRef === 'string')
+                    visit(fnRef, expr.sourceSpan ?? expr.operation.sourceSpan);
+            }
+        });
+    });
+}
+/** Collect the set of bus object names referenced (read/called) in a body. */
+function collectBusAccesses(stmts, hits) {
+    for (const stmt of stmts) {
+        collectBusAccessesInStatement(stmt, hits);
+        const nested = getNestedStatements(stmt);
+        if (nested)
+            collectBusAccesses(nested, hits);
+    }
+}
+function collectBusAccessesInStatement(stmt, hits) {
+    const s = stmt;
+    // Method calls like Wire.begin() / I2C0.writeByte(...): callee is "Wire.begin".
+    if (s.callee && typeof s.callee === 'string') {
+        const base = s.callee.split('.')[0];
+        if (isBusName(base))
+            hits.push({ name: base, span: s.sourceSpan });
+    }
+    // Identifier references (Wire, Serial, I2C0 used bare).
+    const visit = (expr) => {
+        if (expr && typeof expr === 'object' && expr.kind === 'identifier' && typeof expr.value === 'string') {
+            if (isBusName(expr.value))
+                hits.push({ name: expr.value, span: expr.sourceSpan });
+        }
+    };
+    walkExpressionsInStatementLocal(stmt, visit);
+}
+function walkExpressionsInStatementLocal(stmt, visitor) {
+    const s = stmt;
+    if (s.initializer && typeof s.initializer === 'object')
+        walkExpressionsInExpressionLocal(s.initializer, visitor);
+    if (s.value && typeof s.value === 'object' && 'kind' in s.value)
+        walkExpressionsInExpressionLocal(s.value, visitor);
+    if (s.condition && typeof s.condition === 'object')
+        walkExpressionsInExpressionLocal(s.condition, visitor);
+    if (s.expression && typeof s.expression === 'object' && 'kind' in s.expression)
+        walkExpressionsInExpressionLocal(s.expression, visitor);
+    if (Array.isArray(s.args))
+        for (const a of s.args)
+            walkExpressionsInExpressionLocal(a, visitor);
+    if (s.callee && typeof s.callee === 'object')
+        walkExpressionsInExpressionLocal(s.callee, visitor);
+}
+function walkExpressionsInExpressionLocal(expr, visitor) {
+    if (!expr || typeof expr !== 'object')
+        return;
+    visitor(expr);
+    for (const k of ['left', 'right', 'object', 'property', 'value', 'condition', 'whenTrue', 'whenFalse', 'expression', 'callee', 'target']) {
+        const v = expr[k];
+        if (v && typeof v === 'object' && 'kind' in v)
+            walkExpressionsInExpressionLocal(v, visitor);
+    }
+    if (Array.isArray(expr.args))
+        for (const a of expr.args)
+            walkExpressionsInExpressionLocal(a, visitor);
+    if (Array.isArray(expr.elements))
+        for (const a of expr.elements)
+            walkExpressionsInExpressionLocal(a, visitor);
+}
+function getNestedStatements(stmt) {
+    // Reuse the walk-ir helper if it exposes nesting; otherwise return undefined.
+    const s = stmt;
+    if (Array.isArray(s.body))
+        return s.body;
+    if (Array.isArray(s.statements))
+        return s.statements;
+    if (s.thenBlock && Array.isArray(s.thenBlock.statements))
+        return s.thenBlock.statements;
+    if (s.elseBlock && Array.isArray(s.elseBlock.statements))
+        return s.elseBlock.statements;
+    return undefined;
+}
+/** Find a function in program.functions by name (or originalName). */
+function findFunctionByName(program, name) {
+    return program.functions.find((fn) => fn.name === name || fn.originalName === name);
+}
+/**
+ * Analyze worker isolation: (a) promote volatile for worker-shared globals,
+ * (b) flag shared-mutable globals, (c) hard-error on bus access in workers.
+ *
+ * Mutates the IR for (a) (sets isVolatile=true on qualifying var_decls) and
+ * pushes diagnostics for all three tiers. Returns the diagnostics it added.
+ */
+export function analyzeWorkerIsolation(program, diagnostics) {
+    const added = [];
+    const push = (d) => { diagnostics.push(d); added.push(d); };
+    // 1. Identify worker-submitted functions via worker.submit HAL ops.
+    const workerFnNames = new Set();
+    scanForWorkerSubmitOps(program, (fnRef) => {
+        // fnRef is the C++ symbol; the IR function name is usually the same root.
+        workerFnNames.add(fnRef);
+    });
+    if (workerFnNames.size === 0)
+        return added;
+    // 2. Collect the bodies of worker functions present in this program.
+    const workerBodies = [];
+    for (const name of workerFnNames) {
+        const fn = findFunctionByName(program, name);
+        if (fn && Array.isArray(fn.statements))
+            workerBodies.push(fn.statements);
+    }
+    if (workerBodies.length === 0)
+        return added;
+    // ── Tier (b): bus access in workers → HARD ERROR ────────────────────────
+    for (let i = 0; i < workerFnNames.size; i++) {
+        const name = [...workerFnNames][i];
+        const fn = findFunctionByName(program, name);
+        if (!fn || !Array.isArray(fn.statements))
+            continue;
+        const busHits = [];
+        collectBusAccesses(fn.statements, busHits);
+        for (const hit of busHits) {
+            push({
+                severity: 'error',
+                message: `Worker function '${name}' accesses bus '${hit.name}'. Bus access is forbidden in worker functions because the take()/release() bus-ownership lock is not implemented at runtime — two threads would race on the wire despite validation passing.`,
+                hint: `Keep workers compute/pure-only. Bus-sharing workers require the take()/release() runtime backend (a planned follow-on).`,
+                filePath: (hit.span ?? fn.sourceSpan)?.filePath,
+                line: (hit.span ?? fn.sourceSpan)?.startLine,
+                column: (hit.span ?? fn.sourceSpan)?.startColumn,
+                code: 'worker-bus-access-forbidden',
+                source: 'worker-analysis',
+            });
+        }
+    }
+    // ── Tier (a): shared globals → volatile + warning ───────────────────────
+    const globalVars = new Map();
+    for (const stmt of program.topLevelStatements) {
+        if (stmt.kind === 'var_decl' && typeof stmt.name === 'string') {
+            globalVars.set(stmt.name, stmt);
+        }
+    }
+    if (globalVars.size === 0)
+        return added;
+    // Names assigned inside worker bodies.
+    const workerAssigned = new Set();
+    for (const body of workerBodies)
+        collectAssignedNames(body, workerAssigned);
+    if (workerAssigned.size === 0)
+        return added;
+    // Names assigned AND read in main (non-worker) code.
+    const mainAssigned = new Set();
+    const mainRead = new Set();
+    for (const stmt of program.topLevelStatements) {
+        collectReadNames([stmt], mainRead);
+        collectAssignedNames([stmt], mainAssigned);
+    }
+    for (const fn of program.functions) {
+        // Skip the worker functions themselves when collecting main usage.
+        if (workerFnNames.has(fn.name) || workerFnNames.has(fn.originalName))
+            continue;
+        if (Array.isArray(fn.statements)) {
+            collectReadNames(fn.statements, mainRead);
+            collectAssignedNames(fn.statements, mainAssigned);
+        }
+    }
+    for (const [name, stmt] of globalVars) {
+        if (!workerAssigned.has(name))
+            continue;
+        const workerShared = stmt;
+        if (mainRead.has(name) && !mainAssigned.has(name)) {
+            // worker-written + main-read → promote to volatile (the barrier makes the
+            // write visible; volatile stops the compiler caching the read).
+            if (!workerShared.isVolatile) {
+                workerShared.isVolatile = true;
+                push({
+                    severity: 'info',
+                    message: `'${name}' is written in a worker function and read in main code — emitted as \`volatile\` so the compiler does not cache it in a register across the worker/main boundary.`,
+                    filePath: workerShared.sourceSpan?.filePath,
+                    line: workerShared.sourceSpan?.startLine,
+                    column: workerShared.sourceSpan?.startColumn,
+                    code: 'volatile-worker-shared',
+                    source: 'worker-analysis',
+                });
+            }
+        }
+        else if (mainAssigned.has(name)) {
+            // worker-written + main-written → true data race; barrier alone can't fix.
+            push({
+                severity: 'warning',
+                message: `'${name}' is written by both a worker function and main-thread code — a data race the worker completion barrier alone cannot fix. Restructure so only one side writes it (e.g. the worker writes; main only reads).`,
+                hint: `Move all writes to '${name}' into the worker (or into main); do not mutate it from both.`,
+                filePath: workerShared.sourceSpan?.filePath,
+                line: workerShared.sourceSpan?.startLine,
+                column: workerShared.sourceSpan?.startColumn,
+                code: 'worker-shared-mutable',
+                source: 'worker-analysis',
+            });
+        }
+    }
+    return added;
+}

package/dist/orchestrator/graph-builder.js

@@ -121,7 +121,7 @@ export function collectTranspileGraph(entryFile, boardPackage) {
                 }
                 if (!moduleSpecifier)
                     continue;
-                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui")
+                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety")
                     continue;
                 if (moduleSpecifier.startsWith("@typecad/"))
                     continue;
@@ -159,12 +159,13 @@ export function collectTranspileGraph(entryFile, boardPackage) {
             if (moduleSpecifier === "@typecad/expect") {
                 continue;
             }
-            // Skip @typecad/ui (and the future @typecad/ui rename) — it provides
-            // compile-time authoring stubs only. ui.mount/signal/bind calls are
-            // intercepted by tryResolveUICall and lowered to IR; the package itself
-            // must NOT be emitted as a C++ module (it would synthesize a bogus
-            // _ui_t struct for the `ui` namespace value).
-            if (moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/ui") {
+            // Skip @typecad/ui and @typecad/safety — they provide compile-time
+            // authoring stubs only. Their calls (ui.mount/signal/bind, safe.read)
+            // are intercepted at IR-build time and lowered to IR; the packages
+            // themselves must NOT be emitted as C++ modules (they would synthesize
+            // bogus _ui_t / _safe_t structs). All runtime definitions the user code
+            // needs (enums, structs, shims) are provided by the safety polyfill.
+            if (moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety") {
                 continue;
             }
             // Skip @typecad/board, @typecad/board-*, @typecad/mcu-*, @typecad/hal,

package/dist/platform/coop-scheduler-runtime.d.ts

@@ -0,0 +1,19 @@
+import type { ProgramIR } from "../api/index.js";
+import type { RuntimePolyfillIR } from "../api/shared/index.js";
+import type { AsyncRuntimeConfig } from "../api/shared/index.js";
+/**
+ * Build a RuntimePolyfillIR for the no-STL cooperative scheduler, when the
+ * program has async/timer work AND the strategy has opted into priority/time-
+ * budget scheduling via AsyncRuntimeConfig.
+ *
+ * The polyfill carries only the scheduler namespace + CoopSched_run() alias.
+ * Per-program work-unit registration + dispatch lines are emitted separately
+ * by each strategy's asyncLoopInjection() via buildCoopSchedInjection().
+ *
+ * Why a polyfill and not shimLines(): polyfills are dead-code-eliminated
+ * (filterPolyfillHelpers) and feature-gated centrally, matching how
+ * async_runtime / timer_methods are handled. The scheduler is STL-free, so it
+ * links on minimal-libc targets (Zephyr) where the std::function Promise
+ * runtime does not.
+ */
+export declare function buildCoopSchedulerPolyfill(_program: ProgramIR, config: AsyncRuntimeConfig, currentTimeExpr?: string): RuntimePolyfillIR | null;

package/dist/platform/coop-scheduler-runtime.js

@@ -0,0 +1,41 @@
+import { generateCoopScheduler } from "../api/shared/index.js";
+/**
+ * Build a RuntimePolyfillIR for the no-STL cooperative scheduler, when the
+ * program has async/timer work AND the strategy has opted into priority/time-
+ * budget scheduling via AsyncRuntimeConfig.
+ *
+ * The polyfill carries only the scheduler namespace + CoopSched_run() alias.
+ * Per-program work-unit registration + dispatch lines are emitted separately
+ * by each strategy's asyncLoopInjection() via buildCoopSchedInjection().
+ *
+ * Why a polyfill and not shimLines(): polyfills are dead-code-eliminated
+ * (filterPolyfillHelpers) and feature-gated centrally, matching how
+ * async_runtime / timer_methods are handled. The scheduler is STL-free, so it
+ * links on minimal-libc targets (Zephyr) where the std::function Promise
+ * runtime does not.
+ */
+export function buildCoopSchedulerPolyfill(_program, config, currentTimeExpr = "millis()") {
+    if (!config.enablePriority && !config.enableTimeBudget)
+        return null;
+    return {
+        kind: "polyfill",
+        id: "coop_scheduler",
+        domain: "embedded",
+        // STL-free: only needs a 32-bit unsigned time source (millis() /
+        // k_uptime_get_32()) and fixed-width types, both available everywhere.
+        requiredIncludes: [],
+        forwardDeclarations: [],
+        helperStructs: [
+            generateCoopScheduler({
+                capacity: 8,
+                priorities: config.schedulerPriorities ?? 2,
+                enableTimeBudget: config.enableTimeBudget ?? false,
+                timeBudgetMs: config.timeBudgetMs ?? 5,
+                currentTimeExpr,
+            }),
+        ],
+        helperFunctions: [],
+        shimMacros: [],
+        dependencies: [],
+    };
+}

package/dist/platform/generic-strategy.d.ts

@@ -17,7 +17,9 @@ export declare class GenericStrategy implements PlatformStrategy {
     overrideBaseName(originalBaseName: string, _outDirBaseName: string, _isEntryFile: boolean, _isNpmPackage: boolean): string;
     effectiveEmitMode(requestedMode: string, _isNpmPackage: boolean): string;
     normalizeCppType(typeName: string): string;
-    defaultNumericType(): string;
+    defaultNumericType(compliance?: {
+        isBanned(ruleId: string): boolean;
+    }): string;
     mapReturnType(_functionName: string, returnType: string): string;
     isStringLikeType(cppType: string): boolean;
     isPointerType(cppType: string): boolean;
@@ -54,8 +56,8 @@ export declare class GenericStrategy implements PlatformStrategy {
     structFieldInitializer(_fieldValue: ExpressionIR, _compiletimeVarNames: Set<string>, _renderExpr: (e: ExpressionIR) => string): string | undefined;
     getAsyncRuntimeConfig(): AsyncRuntimeConfig;
     generateNativePolyfills(program: ProgramIR, ctx?: PlatformContext): RuntimePolyfillIR[];
-    asyncLoopInjection(_taskVarNames: string[], config: AsyncRuntimeConfig): string[];
-    asyncLoopInjection(_taskVarNames: string[], hasPromiseRuntime: boolean): string[];
+    asyncLoopInjection(taskVarNames: string[], config: AsyncRuntimeConfig): string[];
+    asyncLoopInjection(taskVarNames: string[], hasPromiseRuntime: boolean): string[];
     asyncDriverFunctionName(): string;
     shouldSkipTypeAlias(_cppType: string): boolean;
     emitDiagnostics(_emitMode: string): Diagnostic[];
@@ -68,6 +70,7 @@ export declare class GenericStrategy implements PlatformStrategy {
         close: string;
     } | undefined;
     getStdLibSupport(_architecture?: string): StdLibSupport;
+    debugMode(_target?: string): 'gdb' | 'printf';
     generateDebugInitCode(): string[];
     generateDebugBreakpointCode(params: {
         fileName: string;
@@ -98,4 +101,13 @@ export declare class GenericStrategy implements PlatformStrategy {
     supportedDisplayDrivers(): ReadonlySet<string>;
     colorFormat(): "rgb565" | "rgb666" | "rgb888" | "mono";
     graphicsCapacity(): GraphicsCapacity;
+    readDigitalPin(_pin: string): string;
+    readAnalogPin(_pin: string): string;
+    writeDigitalPin(_pin: string, _val: string): string;
+    setPinMode(_pin: string, _mode: string): string;
+    delayMs(_ms: string): string;
+    delayMicroseconds(_us: string): string;
+    halCallNames(): ReadonlySet<string>;
+    isHalCall(_name: string): boolean;
+    analogReadCallNames(): ReadonlySet<string>;
 }