Mistakes Cuttlefish Catches

Cuttlefish runs about 20 checks in sequence during every build. Each one produces a diagnostic with a severity (error, warning, or info), a message, and usually a suggested fix. The orchestrator is runProgramValidations().

Pin capability validation

Each pin on a board has a defined set of capabilities. The validator checks every HAL method call against the board definition:

import { GPIO, PWM } from '@typecad/hal';
import { A0 } from '@typecad/board';

const pin = new GPIO(A0, GPIO.OUTPUT);
new PWM(A0, { periodNs: 1000000 });  // ERROR: A0 is not a PWM-capable pin

The diagnostic includes the pin name, the requested capability, and suggests which pins do support it.

Peripheral pin conflicts

Many pins serve dual roles. On the ESP32-S3:

• GPIO8 is both a digital pin and I2C data (SDA)
• GPIO12 is both a digital pin and SPI data (MOSI)
• GPIO43/GPIO44 carry the console UART

Using a pin for GPIO while its peripheral is active produces a conflict diagnostic.

Pin alias conflicts

The same physical pin can be referenced by different names:

import { ADC, GPIO } from '@typecad/hal';
import { A4, SDA } from '@typecad/board';

const analog = new ADC(A4);
const i2c = new GPIO(SDA, GPIO.OUTPUT);  // WARNING: A4 and SDA are the same physical pin

Interrupt (ISR) safety

The validator scans interrupt-handler callbacks for operations that are unsafe in interrupt context. Detection covers user-written lambdas (onInterrupt(...) handlers) as well as HAL-authoring callback() directives — Cuttlefish tracks which callbacks are bound to interrupts across the whole program:

Platforms can customize this list via PlatformStrategy.isrUnsafeOperations().

Example

button.onInterrupt(GPIO.INT_EDGE_FALLING, () => {
  UART0.writeLine(" ISR!");          // info: output blocks until the TX FIFO has room
  chip.device(0x50).write([0x50]);   // warning: I2C transactions may sleep
});

Duplicate handler detection

Attaching multiple handlers to the same pin is also flagged:

button.onInterrupt(GPIO.INT_EDGE_FALLING, () => { /* handler 1 */ });
button.onInterrupt(GPIO.INT_EDGE_FALLING, () => { /* handler 2 */ });
// WARNING: Duplicate interrupt handler on the pin

Automatic volatile inference

The classic embedded bug: a global flag set in an interrupt and polled in loop() becomes an infinite loop under -Os because the compiler caches it in a register. Cuttlefish knows which callbacks are interrupts and which globals they write — so it auto-marks shared variables volatile without any annotation:

let flag = false;

function setup() {
  button.onInterrupt(GPIO.INT_EDGE_FALLING, () => { flag = true; });
}

function loop() {
  if (flag) { /* ... */ flag = false; }
}
// INFO: 'flag' is written in an interrupt handler and read in main code
//       — emitted as `volatile` to prevent register caching.

The emitted C++ declares volatile bool flag = false; automatically. This eliminates a class of bugs the C++ compiler cannot detect — “this function runs in interrupt context” is a call-graph property, not a function property.

Reentrancy detection

If a function is called from both an interrupt and main-thread code, an interrupt firing mid-execution can corrupt local state:

function process() { /* ... */ }

function setup() {
  button.onInterrupt(GPIO.INT_EDGE_FALLING, () => { process(); });  // called from interrupt
}

function loop() {
  process();  // also called from main — reentrancy risk
}
// WARNING: 'process' is called from both an interrupt handler and main-thread code.

Memory budget validation

On embedded targets the SRAM is shared by globals, heap, and stack with no memory protection — a collision corrupts memory silently. Cuttlefish compares its static memory estimate against the board’s SRAM budget:

// 900 int32_t values = 3600 bytes on a board with a small SRAM budget
const buf: int32_t[] = [/* ... 900 zeros ... */];
// WARNING: Estimated SRAM usage exceeds the board's budget
//          (statics 3.53 KB + stack ~0.03 KB = ~3.56 KB).
//          This will likely corrupt memory at runtime.

The estimate accounts for global variables, struct sizes, string literals, unsized arrays (element count recovered from the initializer), and call-stack depth. The board’s SRAM size is resolved from the board definition or an architecture-specific fallback.

ADC range validation

Reads beyond the board’s ADC resolution are flagged:

import { ADC } from '@typecad/hal';
import { A0 } from '@typecad/board';

const value = new ADC(A0).read();
if (value > 4095) { /* ... */ }
// WARNING: a 12-bit ADC reads 0-4095. Values above 4095 are unreachable.

Validation is board-data-driven — returns no diagnostic when board data is missing.

Ownership analysis

The ownership validator implements Rust-inspired rules for transpile-time validation. It is opt-in — if no ownership types appear in the program, only const-suggestion checks run.

Use-after-move

let buf: Owned = new Buffer(64);
let other = buf;       // ownership transferred
buf.read();            // ERROR: 'buf' was moved and cannot be used again
// Hint: const buf_ref: Shared = buf; // add this before the move

Assign to immutable borrow

const ref: Shared = data;
ref = newData;         // ERROR: Cannot assign to 'ref' — it is an immutable borrow
// Hint: Change to Mutable if reassignment is needed

Owned copy warning

let buf: Owned = new Buffer(64);
let copy = buf;        // INFO: Non-primitive Owned creates a C++ copy
// Hint: const copy: Shared = buf; // borrow by reference instead

Return local reference

function getData(): Shared {
  const local: Owned = new Buffer(64);
  return local;        // ERROR: Returning borrow of local variable — dangling reference
}

Const promotion

When the whole-program reassignment analysis proves a let is never written after initialization, Cuttlefish automatically emits it as const in C++ — enabling ROM placement and constant folding:

let x = 42;            // INFO: 'x' is never reassigned — emitted as `const`
// Emitted: const int x = 42;

This is information the C++ compiler cannot recover across translation units. The inverse demotion (const → non-const when a member is mutated) also applies automatically.

Borrow mismatch

function process(data: Mutable) { /* ... */ }
const readonly: Shared = buffer;
process(readonly);     // ERROR: Cannot pass Shared to Mutable parameter

Peripheral ownership

When you opt into bus ownership by calling take(), all subsequent bus access must occur within a taken section:

Double take

I2C0.take();
I2C0.take();           // ERROR: Double-take — I2C0 is already owned
// Hint: Call 'I2C0.release()' before taking it again

Unowned release

I2C0.release();        // WARNING: I2C0.release() called but bus was not taken
// Hint: Ensure you call 'I2C0.take()' before releasing

Unowned access

I2C0.take();
I2C0.release();
I2C0.device(0x50).write(data);      // ERROR: Unowned access — I2C0 used outside a claim
// Hint: Call 'const bus = I2C0.take();' and use the returned object

Leak detection

SPI0.take();
// ... end of program
// WARNING: SPI0 was taken but never released
// Hint: Call 'SPI0.release()' when finished

Bus names recognized: I2C0/I2C1, SPI0/SPI1, UART0, Wire, Serial.