@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.10

package/dist/ir/type-resolution.js

@@ -33,9 +33,9 @@ const PIN_INTERFACE_TYPE_NAMES = new Set([
     "PinMode", "InterruptMode",
 ]);
 const BUS_INTERFACE_TYPE_NAMES = new Set([
-    "II2CBus", "ISPIBus", "ISerialPort", "IUART",
+    "II2CBus", "ISPIBus", "ISerialPort",
     "I2CConfig", "SPIConfig", "UARTConfig",
-    "I2CAddress", "UARTStatus", "SPITransferOptions",
+    "I2CAddress", "SPITransferOptions",
 ]);
 const STRATEGY_TYPE_NAMES = new Set([
     "NativeStrategy", "ArduinoStrategy", "BoardStrategy",
@@ -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/unit-suspicion-validation.js

@@ -130,7 +130,7 @@ function checkSPIFrequency(value) {
  * baud rate used as SPI freq, etc.). Only literal numbers are checked —
  * expressions/variables are opaque to this validator.
  */
-function checkConfigValue(kind, rawValue, diagnostics) {
+function checkConfigValue(kind, rawValue, filePath, diagnostics) {
     // HAL ops carry resolved numeric values as `number` when the source arg was
     // a literal, or as `string` expression text otherwise. Only check numbers.
     const value = typeof rawValue === 'number' ? rawValue
@@ -146,6 +146,7 @@ function checkConfigValue(kind, rawValue, diagnostics) {
             severity: 'warning',
             message,
             code: 'unit-suspicion',
+            filePath,
             source: 'unit-suspicion-validation',
         });
     }
@@ -160,15 +161,16 @@ function scanStatement(stmt, diagnostics) {
     if (!stmt || typeof stmt !== 'object')
         return;
     const s = stmt;
+    const filePath = s.sourceSpan?.filePath;
     // HAL-op statements carry structured operations with resolved values.
     if (stmt.kind === 'hal-op' && s.operation) {
         const op = s.operation;
         switch (op.operation) {
             case 'i2c.set_clock':
-                checkConfigValue('i2c', op.hz, diagnostics);
+                checkConfigValue('i2c', op.hz, filePath, diagnostics);
                 break;
             case 'uart.begin':
-                checkConfigValue('baud', op.baud, diagnostics);
+                checkConfigValue('baud', op.baud, filePath, diagnostics);
                 break;
             // SPI frequency flows through SPISettings construction text, which the
             // HAL op carries as a string — the numeric extraction in
@@ -178,7 +180,7 @@ function scanStatement(stmt, diagnostics) {
                     // SPISettings({freq}, ...) — try to extract the leading frequency.
                     const m = op.settings.match(/^\s*(\d+)/);
                     if (m)
-                        checkConfigValue('spi', parseInt(m[1], 10), diagnostics);
+                        checkConfigValue('spi', parseInt(m[1], 10), filePath, diagnostics);
                 }
                 break;
         }
@@ -188,18 +190,18 @@ function scanStatement(stmt, diagnostics) {
     if (stmt.kind === 'call' && typeof s.callee === 'string' && Array.isArray(s.args)) {
         const method = s.callee.split('.').pop() ?? s.callee;
         if (method === 'setClock' && s.args.length >= 2) {
-            checkConfigValue('i2c', extractNumericValue(s.args[1]), diagnostics);
+            checkConfigValue('i2c', extractNumericValue(s.args[1]), filePath, diagnostics);
         }
         else if (method === 'setBaudRate' || method === 'begin') {
             // Serial.begin(baud) / setBaudRate(baud) — last numeric arg is the baud.
             for (const arg of s.args) {
                 const v = extractNumericValue(arg);
                 if (v !== undefined)
-                    checkConfigValue('baud', v, diagnostics);
+                    checkConfigValue('baud', v, filePath, diagnostics);
             }
         }
         else if (method === 'setFrequency' && s.args.length >= 2) {
-            checkConfigValue('spi', extractNumericValue(s.args[1]), diagnostics);
+            checkConfigValue('spi', extractNumericValue(s.args[1]), filePath, diagnostics);
         }
     }
     // Recurse into nested statements

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";
@@ -18,21 +19,26 @@ import { validateBlockingDelayInLoop } from "./timing-validation.js";
 import { validateUnitSuspicion } from "./unit-suspicion-validation.js";
 import { validateOwnership } from "./ownership-analysis.js";
 import { validatePinCapabilities } from "./pin-capability-validation.js";
+import { validateNetworkUsage } from "./network-validation.js";
 export function runProgramValidations(program, strategy) {
     const resolvedStrategy = strategy ?? (hasLoadedFramework() ? getLoadedFramework().strategy : resolveStrategy('generic'));
     const diagnostics = [];
     const peripheralUsage = program.peripheralUsage ?? createEmptyPeripheralUsage();
     diagnostics.push(...validatePinCapabilities(program));
-    diagnostics.push(...validatePeripherals(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validateUnsafePins(peripheralUsage, program.boardConstants));
+    diagnostics.push(...validatePeripherals(peripheralUsage, program.boardConstants, program.fileName));
+    diagnostics.push(...validateUnsafePins(peripheralUsage, program.boardConstants, program.fileName));
     diagnostics.push(...analyzeResources(program, resolvedStrategy));
-    diagnostics.push(...validatePinAliasConflicts(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validatePWMTimerSharing(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validateTimer0PWMTimingConflict(peripheralUsage, program.boardConstants));
-    diagnostics.push(...validatePulldownSupport(peripheralUsage, program.boardConstants));
-    diagnostics.push(...analyzeInterruptSafety(program, peripheralUsage));
+    diagnostics.push(...validatePinAliasConflicts(peripheralUsage, program.boardConstants, program.fileName));
+    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, 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));
@@ -40,6 +46,7 @@ export function runProgramValidations(program, strategy) {
     diagnostics.push(...validateOwnership(program));
     diagnostics.push(...validateTryCatch(program, program.boardConstants, resolvedStrategy));
     diagnostics.push(...validateMemoryBudget(program, program.boardConstants));
-    diagnostics.push(...validateBlockingDelayInLoop(program));
+    diagnostics.push(...validateBlockingDelayInLoop(program, resolvedStrategy));
+    diagnostics.push(...validateNetworkUsage(program));
     return diagnostics;
 }

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/libdef/c-to-decl.d.ts

@@ -0,0 +1,27 @@
+/**
+ * C-header to TypeScript declaration generator.
+ *
+ * Complements cpp-to-decl.ts (which is class-focused). ESP-IDF components
+ * are mostly C: free functions, opaque handles, typedef'd enums and structs.
+ *
+ * EMISSION POLICY — names match the C header 1-to-1.
+ *
+ *   esp_err_t esp_wifi_init(const wifi_config_t *config);
+ *
+ * becomes
+ *
+ *   export declare function esp_wifi_init(config: number): esp_err_t;
+ *
+ * not `esp_wifi.init(...)`. ESP-IDF examples call `esp_wifi_init`, never
+ * `esp_wifi.init`; the dotted form has no C++ representation (there is no
+ * `esp_wifi` object or namespace in the real header) and would not link.
+ * Mirroring the C names verbatim means the transpiler lowers TS calls
+ * directly to valid C with zero translation.
+ *
+ * Spec: docs/superpowers/specs/2026-07-19-demo-wifi-design.md
+ */
+/**
+ * Top-level entry: read a header file, write `<header>.d.ts` alongside it.
+ * Returns the output path, or null if no declarations could be extracted.
+ */
+export declare function generateCDecl(filePath: string, outputPath?: string): string | null;