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

package/dist/api/shared/platform-strategy.d.ts

@@ -108,8 +108,13 @@ export interface PlatformTypeStrategy {
      * when the enum members map directly to platform preprocessor macros.
      */
     passthroughEnumNames?(): ReadonlySet<string>;
-    /** Default numeric type for the platform (e.g. "int" on hosted, "int32_t" on embedded). */
-    defaultNumericType(): string;
+    /**
+     * Default numeric type for the platform (e.g. "int" on hosted, "int32_t" on embedded).
+     * Optional compliance context: when A3-9-1 is enforced, returns a fixed-width type.
+     */
+    defaultNumericType(compliance?: {
+        isBanned(ruleId: string): boolean;
+    }): string;
     /**
      * Inform the strategy which enums have values exceeding the signed 16-bit range.
      * The strategy can use this to choose an appropriate underlying type.
@@ -307,12 +312,32 @@ export interface PlatformBuildStrategy {
     /** Standard library support for the given architecture. */
     getStdLibSupport(architecture?: string): StdLibSupport;
 }
+/**
+ * Coarse C++ type category carried per debug variable, so printf-based codegens
+ * (ESP-IDF) can pick the right format specifier. Inferred by the debug
+ * preprocessor from AST shape (no TypeChecker); `unknown` is the fallback.
+ * Mirrors `DebugCppType` in cuttlefish/src/debug/types.ts — duplicated here to
+ * avoid a cross-module import from the api surface.
+ */
+export type DebugCppType = 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
 /**
  * Debug code generation sub-interface.
  * Frameworks implement these to provide platform-specific debug output
  * (e.g., Serial.println on embedded, std::cout on hosted targets).
  */
 export interface PlatformDebugStrategy {
+    /**
+     * Debug mode for the given build target. Controls whether `--debug` emits
+     * GDB-oriented output (`#line` directives + debug config artifacts, value
+     * `'gdb'`) or the legacy printf/Serial instrumentation (`'printf'`).
+     *
+     * Frameworks that support native source-level debugging for a chip return
+     * `'gdb'` for that target; everything else inherits the `'printf'` default
+     * and the existing instrumentation path is used unchanged.
+     *
+     * @param target the frameworkData.buildTarget value (e.g. 'esp32s3')
+     */
+    debugMode?(target?: string): 'gdb' | 'printf';
     /** Generate initialization code for the debug subsystem. */
     generateDebugInitCode?(): string[];
     /** Generate code for a breakpoint with optional condition and variable dump. */
@@ -323,8 +348,16 @@ export interface PlatformDebugStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: DebugCppType;
         }>;
         normalizedCondition?: string;
+        /**
+         * Stable per-file ID assigned by the preprocessor. When present, the
+         * codegen emits a `static bool __tc_bp_disabled_<id>` flag and wraps the
+         * halt in `if (!__tc_bp_disabled_<id>)`, so the user can skip/disable this
+         * one breakpoint for the rest of the run (the 's' key sets the flag).
+         */
+        breakpointId?: number;
     }): string[];
     /** Generate code for a logpoint with interpolated message parts. */
     generateDebugLogpointCode?(params: {
@@ -337,6 +370,7 @@ export interface PlatformDebugStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: DebugCppType;
         }>;
     }): string[];
 }
@@ -371,6 +405,27 @@ export interface PlatformAsyncStrategy {
         preIteration: string;
         postIteration: string;
     } | null;
+    /**
+     * C++ statements that spawn the worker for slot `handleId`, running
+     * `fn(arg)`. Emitted as the body of __tc_worker_submit. Return undefined
+     * to declare worker offload unsupported on this framework.
+     *
+     * The shared runtime has already recorded `waiter`/set `done=false` before
+     * this runs; the hook need only spawn. `fn` and `arg` are C++ expressions
+     * (a function pointer and a void*).
+     */
+    workerSpawnLines?(handleId: number, fn: string, arg: string): string[] | undefined;
+    /**
+     * C++ expression the worker calls AFTER completing its work and writing its
+     * outputs, to signal completion to the waiter. Emitted inside the worker
+     * trampoline. Must issue a memory barrier. Return undefined if unsupported.
+     */
+    workerSignalDoneExpr?(handleId: number): string | undefined;
+    /**
+     * C++ boolean expression polled by __tc_worker_done to test completion.
+     * Must observe the signal's memory barrier. Return undefined if unsupported.
+     */
+    workerIsDoneExpr?(handleId: number): string | undefined;
 }
 /**
  * Strategy for resolving semantic HAL operations to framework-specific C++.
@@ -403,6 +458,53 @@ export interface PlatformHALStrategy {
      * Default true (preserves existing behavior for hardware strategies).
      */
     modelsGpio?(): boolean;
+    /**
+     * C++ expression that reads the digital level of a pin (HIGH/LOW).
+     * ArduinoStrategy returns `digitalRead(${pin})`. GenericStrategy returns a
+     * documented no-op stub (no GPIO on host).
+     */
+    readDigitalPin?(pin: string): string;
+    /**
+     * C++ expression that reads a raw analog value from an ADC pin.
+     * ArduinoStrategy returns `analogRead(${pin})`. GenericStrategy stubs.
+     */
+    readAnalogPin?(pin: string): string;
+    /**
+     * C++ statement that writes a digital level to a pin.
+     * ArduinoStrategy returns `digitalWrite(${pin}, ${val})`. Cuttlefish does not
+     * call this in the current emit path (display reset moves to the framework),
+     * but it is part of the atomic surface for completeness/future use.
+     */
+    writeDigitalPin?(pin: string, val: string): string;
+    /**
+     * C++ statement that configures a pin's mode.
+     * ArduinoStrategy returns `pinMode(${pin}, ${mode})`.
+     */
+    setPinMode?(pin: string, mode: string): string;
+    /**
+     * C++ statement that blocks for a number of milliseconds.
+     * ArduinoStrategy returns `delay(${ms})`.
+     */
+    delayMs?(ms: string): string;
+    /**
+     * C++ statement that blocks for a number of microseconds.
+     * ArduinoStrategy returns `delayMicroseconds(${us})`.
+     */
+    delayMicroseconds?(us: string): string;
+    /**
+     * The full set of HAL call names this framework's emitted code may contain
+     * (digitalRead, analogRead, Serial, tone, millis, …). Used to recognize HAL
+     * calls in rendered C++ text where no structured HAL-IR node is available.
+     */
+    halCallNames?(): ReadonlySet<string>;
+    /** Membership test against {@link halCallNames}. Default false on generic. */
+    isHalCall?(name: string): boolean;
+    /**
+     * The subset of {@link halCallNames} that return an analog-read integer
+     * value (e.g. analogRead). Used by adc-range-validation to detect ADC reads
+     * in lowered raw text.
+     */
+    analogReadCallNames?(): ReadonlySet<string>;
 }
 /**
  * Full platform strategy composed from focused sub-interfaces.

package/dist/api/shared/polyfill-helper-registry.js

@@ -62,6 +62,22 @@ export const POLYFILL_HELPER_MAP = {
     // JSON helpers
     '__tc_jsonStringify(': ['__tc_jsonStringify'],
     '__tc_jsonParse(': ['__tc_jsonParse'],
+    // Safety helpers — emitted by @typecad/safety's polyfills as global-scope
+    // __tc_safety_* free functions (the polyfill-helper-registry extractor
+    // expects __tc_* immediately followed by `(`, so namespaced names would be
+    // missed). The call-pattern keys are the substrings program analysis scans
+    // source for; the values are the __tc_safety_* names that
+    // filterPolyfillHelpers matches in helperFunctions text.
+    //
+    // Two key forms per helper: the user-facing safe.* source spelling (which
+    // program analysis sees in raw IR before lowering) and the lowered
+    // __tc_safety_* spelling (which appears after the safety call-statement
+    // transformer emits hal-op resolution text). Both map to the same helper.
+    'safe.read(': ['__tc_safety_read_safe'],
+    'safe.write(': ['__tc_safety_write_verify'],
+    '__tc_safety_record_pin_mode(': ['__tc_safety_record_pin_mode'],
+    '__tc_safety_read_safe(': ['__tc_safety_read_safe'],
+    '__tc_safety_write_verify(': ['__tc_safety_write_verify'],
 };
 function extractHelperFunctionNames(funcDef) {
     const matches = funcDef.matchAll(/\b(__tc_[A-Za-z0-9_]+)\s*\(/g);
@@ -82,5 +98,6 @@ export function filterPolyfillHelpers(polyfills, usedHelpers) {
         }),
     })).filter(polyfill => polyfill.helperFunctions.length > 0 ||
         polyfill.forwardDeclarations.length > 0 ||
-        polyfill.helperStructs.length > 0);
+        polyfill.helperStructs.length > 0 ||
+        polyfill.shimMacros.length > 0);
 }

package/dist/api/shared/promise-runtime.d.ts

@@ -7,4 +7,4 @@
  * @param includeWaitForPinEdge Whether to include the `waitForPinEdge` stub
  *   (used by Arduino targets).
  */
-export declare function generatePromiseRuntime(queueCapacity: number, includeWaitForPinEdge?: boolean): string;
+export declare function generatePromiseRuntime(queueCapacity: number, includeWaitForPinEdge?: boolean, strategy?: import("./platform-strategy.js").PlatformStrategy): string;

package/dist/api/shared/promise-runtime.js

@@ -20,7 +20,11 @@
  * @param includeWaitForPinEdge Whether to include the `waitForPinEdge` stub
  *   (used by Arduino targets).
  */
-export function generatePromiseRuntime(queueCapacity, includeWaitForPinEdge = false) {
+export function generatePromiseRuntime(queueCapacity, includeWaitForPinEdge = false, strategy) {
+    // The current-time expression (millis() on Wiring-derived frameworks,
+    // std::chrono on generic). Falling back to millis() preserves the historical
+    // behavior when no strategy is supplied.
+    const now = strategy?.currentTimeMillis?.() ?? "millis()";
     const waitForPinEdge = includeWaitForPinEdge ? `
   // HAL-level wait for pin edge — polling-based implementation.
   // Detects an actual transition (idle→target), not just the current level.
@@ -31,18 +35,18 @@ export function generatePromiseRuntime(queueCapacity, includeWaitForPinEdge = fa
     return Promise<void>([pin, mode, timeout](std::function<void(const void*)> resolve, std::function<void(const std::string&)> reject) {
       int targetState = (mode == RISING) ? HIGH : LOW;
       int idleState = (mode == RISING) ? LOW : HIGH;
-      unsigned long start = millis();
+      unsigned long start = ${now};
       // Phase 2 poller: waits for the pin to reach the target state (the edge).
       auto pollTarget = [pin, targetState, timeout, start, resolve]() {
-        if (digitalRead(pin) == targetState) {
+        if (${strategy?.readDigitalPin?.("pin") ?? "digitalRead(pin)"} == targetState) {
           resolve(nullptr);
-        } else if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) {
+        } else if (timeout >= 0 && (${now} - start >= static_cast<unsigned long>(timeout))) {
           resolve(nullptr);
         } else {
           enqueueMicrotask([pin, targetState, timeout, start, resolve]() {
-            if (digitalRead(pin) == targetState) {
+            if (${strategy?.readDigitalPin?.("pin") ?? "digitalRead(pin)"} == targetState) {
               resolve(nullptr);
-            } else if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) {
+            } else if (timeout >= 0 && (${now} - start >= static_cast<unsigned long>(timeout))) {
               resolve(nullptr);
             } else {
               enqueueMicrotask([pin, targetState, timeout, start, resolve]() {});
@@ -52,9 +56,9 @@ export function generatePromiseRuntime(queueCapacity, includeWaitForPinEdge = fa
       };
       // Phase 1: wait for idle state before watching for the edge.
       enqueueMicrotask([pin, idleState, timeout, start, resolve, pollTarget]() {
-        if (digitalRead(pin) == idleState) {
+        if (${strategy?.readDigitalPin?.("pin") ?? "digitalRead(pin)"} == idleState) {
           pollTarget();
-        } else if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) {
+        } else if (timeout >= 0 && (${now} - start >= static_cast<unsigned long>(timeout))) {
           resolve(nullptr);
         } else {
           enqueueMicrotask([pin, idleState, timeout, start, resolve, pollTarget]() {});
@@ -264,12 +268,12 @@ namespace typecad_async {
   // Async.sleep() — cooperative delay using millis polling
   inline Promise<void> __cuttlefish_async_sleep(unsigned long ms) {
     return Promise<void>([ms](std::function<void(const void*)> resolve, std::function<void(const std::string&)> reject) {
-      unsigned long start = millis();
-      if (millis() - start >= ms) {
+      unsigned long start = ${now};
+      if (${now} - start >= ms) {
         resolve(nullptr);
       } else {
         enqueueMicrotask([ms, start, resolve]() {
-          if (millis() - start >= ms) {
+          if (${now} - start >= ms) {
             resolve(nullptr);
           } else {
             enqueueMicrotask([ms, start, resolve]() { /* will be re-checked next cycle */ });
@@ -289,9 +293,9 @@ namespace typecad_async {
   // Async.sleepUntil() — poll condition every interval ms
   inline Promise<void> __cuttlefish_async_sleep_until(unsigned long pollIntervalMs) {
     return Promise<void>([pollIntervalMs](std::function<void(const void*)> resolve, std::function<void(const std::string&)> reject) {
-      unsigned long start = millis();
+      unsigned long start = ${now};
       enqueueMicrotask([pollIntervalMs, start, resolve]() {
-        if (millis() - start >= pollIntervalMs) {
+        if (${now} - start >= pollIntervalMs) {
           resolve(nullptr);  // caller re-checks condition
         } else {
           enqueueMicrotask([pollIntervalMs, start, resolve]() { /* re-check next cycle */ });

package/dist/api/shared/toolchain-types.d.ts

@@ -31,11 +31,28 @@ export interface ToolchainOptions {
     optimize?: string;
     extraFlags?: string[];
     defines?: Record<string, string>;
+    /** ESP32 PSRAM type ('opi' | 'quad') when the target board has PSRAM. */
+    psram?: 'opi' | 'quad';
     /**
      * Framework-specific config from `cuttlefish.config.ts`.
      * Each framework casts this to its own typed interface.
      */
     frameworkConfig?: Record<string, unknown>;
+    /**
+     * Zephyr-specific config from `cuttlefish.config.ts` (the `zephyr` section).
+     */
+    zephyrConfig?: Record<string, unknown>;
+    /**
+     * Display config from `cuttlefish.config.ts` (the `display` section).
+     * Frameworks use cs/dc/rst/spiFrequency to generate devicetree wiring.
+     */
+    display?: Record<string, unknown>;
+    /**
+     * True when `--debug` is active. Frameworks read this to generate debug
+     * artifacts (e.g. VS Code launch configs, debug Kconfig symbols) and to
+     * select their debug mode (gdb vs printf) via PlatformDebugStrategy.
+     */
+    debug?: boolean;
 }
 /**
  * Generic compile result. All frameworks return this shape.

package/dist/api/shared/validate-framework-manifest.js

@@ -29,6 +29,7 @@ class Accumulator {
 const CATEGORY_PREFIXES = {
     gpio: ['gpio.'],
     pwm: ['pwm.'],
+    rmt: ['rmt.'],
     adc: ['adc.'],
     dac: ['dac.'],
     interrupts: ['interrupt.'],
@@ -46,6 +47,32 @@ const CATEGORY_PREFIXES = {
     http: ['http.'],
     display: ['display.'],
     preferences: ['preferences.'],
+    ble: ['ble.'],
+    random: ['random.'],
+    fs: ['fs.'],
+    mdns: ['mdns.'],
+    mqtt: ['mqtt.'],
+    ota: ['ota.'],
+    temp: ['temp.'],
+    hwtimer: ['hwtimer.'],
+    capacitive: ['capacitive.'],
+    // Unimplemented-but-recognized categories: each framework may declare these
+    // as unsupported in its manifest so the coverage matrix records them as a
+    // roadmap. The validator probes the resolver and confirms it does NOT lower
+    // them (consistent with the 'unsupported' status).
+    i2s: ['i2s.'],
+    twai: ['twai.'],
+    usb: ['usb.'],
+    eth: ['eth.'],
+    espnow: ['espnow.'],
+    crypto: ['crypto.'],
+    pcnt: ['pcnt.'],
+    mcpwm: ['mcpwm.'],
+    // Worker offload + snprintf raw-escape: recognized categories. Frameworks
+    // that lower worker.* declare it supported; snprintf.emit is a raw escape
+    // hatch (declared unsupported by frameworks that don't special-case it).
+    worker: ['worker.'],
+    snprintf: ['snprintf.'],
 };
 function opKindsForCategory(category) {
     const prefixes = CATEGORY_PREFIXES[category] ?? [];
@@ -78,6 +105,36 @@ const OP_PROBE_PAYLOADS = {
     'display.draw_text': { x: 0, y: 0, text: 'x', font: '8x16', color: 0xffff },
     'display.draw_rect': { x: 0, y: 0, w: 10, h: 10, color: 0xffff },
     'display.flush': { rects: [{ x: 0, y: 0, w: 10, h: 10 }] },
+    // fs.* require a path (and content for write_text).
+    'fs.read_text': { path: '/sdcard/x.txt' },
+    'fs.write_text': { path: '/sdcard/x.txt', content: 'hi' },
+    'fs.exists': { path: '/sdcard/x.txt' },
+    'fs.remove': { path: '/sdcard/x.txt' },
+    // random.range requires min/max.
+    'random.range': { min: 0, max: 10 },
+    // mdns.add_service requires instance/proto/port.
+    'mdns.start': { hostname: 'h' },
+    'mdns.set_hostname': { name: 'h' },
+    'mdns.add_service': { instance: 'i', proto: '_tcp', port: 80 },
+    // mqtt.connect requires brokerUri/clientId; mqtt.publish requires topic/data.
+    'mqtt.connect': { brokerUri: 'mqtt://b', clientId: 'c' },
+    'mqtt.on_message': { handler: 'cb' },
+    'mqtt.subscribe': { topic: 't' },
+    'mqtt.publish': { topic: 't', data: 'd' },
+    // wifi.on_event requires an event + handler. Probe with 'connect'.
+    // Without a payload the probe sends event=undefined and a 'supported'
+    // declaration would false-fail as "resolver returned undefined".
+    'wifi.on_event': { event: 'connect', handler: 'cb' },
+    // ota.from_url requires url; ota.write requires chunk.
+    'ota.from_url': { url: 'https://x' },
+    'ota.write': { chunk: 'buf' },
+    // hwtimer.* require an instance (and hz/handler).
+    'hwtimer.set_frequency': { instance: 0, hz: 1000 },
+    'hwtimer.on_overflow': { instance: 0, handler: 'cb' },
+    'hwtimer.start': { instance: 0 },
+    'hwtimer.stop': { instance: 0 },
+    // capacitive.read requires pin.
+    'capacitive.read': { pin: 4 },
 };
 // Builds a HALOpIR probe. Uses OP_PROBE_PAYLOADS when available so resolvers
 // that destructure required fields don't throw on the probe itself.
@@ -232,6 +289,25 @@ function validateHalCoverage(manifest, ctx, acc) {
     }
 }
 // ---------------------------------------------------------------------------
+// Category C2 — HAL completeness
+// ---------------------------------------------------------------------------
+/**
+ * Verify every known HAL category appears in manifest.hal. validateHalCoverage
+ * only audits categories the manifest declares; a category omitted entirely is
+ * invisible to it (and to the per-op check). This step closes that hole: each
+ * category in CATEGORY_PREFIXES must be accounted for, even as unsupported.
+ * `raw` is excluded — it is the schema-level escape hatch, not a real category,
+ * and is not in CATEGORY_PREFIXES.
+ */
+function validateHalCompleteness(manifest, _ctx, acc) {
+    const declared = new Set(Object.keys(manifest.hal));
+    for (const category of Object.keys(CATEGORY_PREFIXES)) {
+        if (!declared.has(category)) {
+            acc.error(`hal/${category}/category-undeclared`, `manifest.hal.${category}`, `manifest.hal is missing the "${category}" category. Add a block declaring it (supported: true/false with ops, or unsupported with unsupportedReason).`, category);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // Category D — polyfills
 // ---------------------------------------------------------------------------
 function validatePolyfills(manifest, ctx, acc) {
@@ -404,6 +480,7 @@ export function validateFrameworkManifest(manifest, ctx) {
     validateIdentity(manifest, ctx, acc);
     validateEntrypoint(manifest, ctx, acc);
     validateHalCoverage(manifest, ctx, acc);
+    validateHalCompleteness(manifest, ctx, acc);
     validatePolyfills(manifest, ctx, acc);
     validateToolchain(manifest, ctx, acc);
     validateLibraryResolution(manifest, ctx, acc);

package/dist/api/shared/worker-runtime-polyfill.d.ts

@@ -0,0 +1,22 @@
+import type { ProgramIR } from "../index.js";
+import type { RuntimePolyfillIR } from "./index.js";
+import type { PlatformStrategy } from "./platform-strategy.js";
+import type { WorkerBacking } from "./worker-runtime.js";
+/**
+ * Build a RuntimePolyfillIR for the worker-offload runtime, when the framework
+ * supplies worker backing via its PlatformAsyncStrategy hooks
+ * (workerSpawnLines / workerSignalDoneExpr / workerIsDoneExpr).
+ *
+ * The polyfill carries only the slot table + __tc_worker_submit/done contract
+ * with the per-framework primitives injected from the strategy hooks. STL-free
+ * so it links on minimal-libc targets (Zephyr). Returns null if the strategy
+ * supplies no backing (worker offload unsupported there) — in which case
+ * worker.* ops resolve to unsupported.
+ *
+ * Callers gate this on the program actually using worker.* ops
+ * (ProgramAnalysisResult.usesWorker); the producer does not re-scan.
+ */
+export declare function buildWorkerRuntimePolyfill(_program: ProgramIR, strategy: PlatformStrategy, backing: WorkerBacking, options?: {
+    poolSize?: number;
+    stackSize?: number;
+}): RuntimePolyfillIR | null;

package/dist/api/shared/worker-runtime-polyfill.js

@@ -0,0 +1,34 @@
+import { generateWorkerRuntime } from "./worker-runtime.js";
+/**
+ * Build a RuntimePolyfillIR for the worker-offload runtime, when the framework
+ * supplies worker backing via its PlatformAsyncStrategy hooks
+ * (workerSpawnLines / workerSignalDoneExpr / workerIsDoneExpr).
+ *
+ * The polyfill carries only the slot table + __tc_worker_submit/done contract
+ * with the per-framework primitives injected from the strategy hooks. STL-free
+ * so it links on minimal-libc targets (Zephyr). Returns null if the strategy
+ * supplies no backing (worker offload unsupported there) — in which case
+ * worker.* ops resolve to unsupported.
+ *
+ * Callers gate this on the program actually using worker.* ops
+ * (ProgramAnalysisResult.usesWorker); the producer does not re-scan.
+ */
+export function buildWorkerRuntimePolyfill(_program, strategy, backing, options = {}) {
+    // The backing is authoritative: it is constructed by the framework from its
+    // own hooks. If a framework supplies no backing (worker offload unsupported),
+    // it should not call this producer.
+    const runtime = generateWorkerRuntime(backing, options);
+    if (!runtime)
+        return null;
+    return {
+        kind: "polyfill",
+        id: "worker_runtime",
+        domain: "embedded",
+        requiredIncludes: backing.requiredIncludes,
+        forwardDeclarations: backing.declarations ?? [],
+        helperStructs: [runtime],
+        helperFunctions: [],
+        shimMacros: [],
+        dependencies: [],
+    };
+}

package/dist/api/shared/worker-runtime.d.ts

@@ -0,0 +1,69 @@
+export interface WorkerRuntimeOptions {
+    /** Number of fixed worker slots in the pool. Default 4. */
+    poolSize?: number;
+    /** Per-slot worker stack size in bytes (ESP32). Default 8192. */
+    stackSize?: number;
+}
+/**
+ * Per-framework backing primitives injected into the shared contract.
+ * Undefined fields mean "unsupported" and the runtime is not emitted.
+ */
+export interface WorkerBacking {
+    /**
+     * Statements that spawn the worker trampoline for slot `handleId`.
+     *
+     * `trampolineName` is the C++ symbol of the per-slot worker function the
+     * shared runtime generated (it reads fn/arg from the slot, runs them, then
+     * signals completion). `waiterExpr` is the C++ lvalue the backing should set
+     * to the current waiter handle before spawning (the shared runtime reads it
+     * via signalDoneExpr/isDoneExpr).
+     *
+     * The shared runtime has already stored the submitted fn/arg into the slot
+     * and cleared `done` before this runs; the backing need only record the
+     * waiter and spawn `trampolineName`.
+     */
+    spawnLines: (handleId: number, trampolineName: string, waiterExpr: string) => string[];
+    /** Expression the worker calls after finishing + writing outputs (barrier). */
+    signalDoneExpr: (handleId: number) => string;
+    /** Boolean expression polled by __tc_worker_done (observes the barrier). */
+    isDoneExpr: (handleId: number) => string;
+    /** C++ headers required by the primitives (e.g. '<freertos/FreeRTOS.h>'). */
+    requiredIncludes: string[];
+    /** Any backing declarations (e.g. semaphore objects) emitted before the pool. */
+    declarations?: string[];
+    /**
+     * Per-slot backing declarations emitted inside the namespace, one call per
+     * slot, before the submit/done functions. Used by backings that need a named
+     * per-slot object bound to the trampoline at definition time — e.g. Zephyr's
+     * `K_WORK_DEFINE(_work_<i>, __tc_worker_fn_<i>)` + a per-slot semaphore.
+     * `trampolineName` is the per-slot worker symbol the shared runtime emitted.
+     */
+    slotDeclarations?: (handleId: number, trampolineName: string) => string[];
+}
+/**
+ * Generate the worker-offload runtime C++ for a framework that supplies a
+ * backing. Returns null if `backing` is null (unsupported on this framework).
+ *
+ * The emitted code defines, for each slot i in [0, poolSize):
+ *   - a worker trampoline __tc_worker_fn_i(void* arg) that runs the recorded
+ *     fn and then signals completion via signalDoneExpr,
+ *   - __tc_worker_submit(i, fn, arg) — records the waiter, clears done, spawns,
+ *   - __tc_worker_done(i) — poll predicate.
+ *
+ * AUTOSAR C++14: fixed-width types, static_cast, final structs, no STL, no heap.
+ */
+export declare function generateWorkerRuntime(backing: WorkerBacking | null, options?: WorkerRuntimeOptions): string | null;
+/**
+ * Resolve a HAL worker.* op to C++ against the shared contract.
+ * Returns undefined for ops the caller did not lower (unsupported).
+ *
+ * Note: the worker function itself (fnRef) and its argument (argRef) come from
+ * the IR as flat-scalar strings (per the hal-op-ir flat-fields contract). The
+ * lowering emits a straight call into __tc_worker_submit / __tc_worker_done.
+ */
+export declare function lowerWorkerOp(op: {
+    operation: string;
+}): {
+    code?: string;
+    expression?: string;
+} | undefined;