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

package/dist/lint-cache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persistent cache for the ESLint build gate.
+ *
+ * ESLint is a mandatory correctness gate: it excludes non-AOT code patterns
+ * that the transpiler cannot accept. Running it on every `cuttlefish build`
+ * costs ~3s (38% of a small-project build) and almost always finds nothing on
+ * repeat runs. Its result (zero errors) is a whole-program boolean that
+ * depends only on a small set of inputs, so it is cleanly cacheable.
+ *
+ * Soundness contract:
+ *   - The cache ONLY records a successful (zero-error) lint result.
+ *   - A failing lint never persists (the build aborts anyway).
+ *   - On ANY input change the entry is invalidated and ESLint runs for real.
+ *   - `options.force` and the `CUTTLEFISH_NO_CACHE` env var bypass entirely.
+ *
+ * This mirrors the historical `.cuttlefish-cache.json` timestamp+hash cache
+ * that used to live in this package. It is scoped to the ESLint gate (and the
+ * type-check gate) rather than the transpile-IR pass, because — unlike IR
+ * lowering — these gates' outcomes are whole-program booleans with no
+ * cross-module rehydration requirement.
+ */
+/** Resolve the eslint config the same way runEslintCheck does, to avoid drift. */
+export declare function resolveEslintConfigPath(projectRoot: string): string | undefined;
+/**
+ * Compute the inputs that the ESLint result depends on. Two builds with the
+ * same fingerprint are guaranteed to produce the same lint outcome.
+ */
+export interface LintFingerprint {
+    digest: string;
+    /** Absolute paths that were hashed into the digest (for debugging). */
+    inputs: string[];
+}
+export declare function computeLintFingerprint(projectRoot: string, srcDir: string): LintFingerprint | null;
+export interface GateCacheResult {
+    /** True when the gate can be skipped because the recorded success still holds. */
+    hit: boolean;
+    /** The fingerprint to record after a successful gate run. */
+    fingerprint: LintFingerprint | null;
+}
+/**
+ * Decide whether the ESLint gate can be skipped for this project.
+ *
+ * Returns `hit: true` only when:
+ *   - caching is not disabled, not force-bypassed,
+ *   - a fingerprint can be computed (config + eslint resolvable), and
+ *   - the on-disk cache records a success for that exact fingerprint.
+ *
+ * `force` mirrors TranspileOptions.force and bypasses the cache.
+ */
+export declare function checkLintCache(projectRoot: string, srcDir: string, opts?: {
+    force?: boolean;
+}): GateCacheResult;
+/**
+ * Record a successful ESLint run (zero errors). Never call this after a
+ * failing run — a failing build must not persist a "clean" marker.
+ */
+export declare function recordLintSuccess(projectRoot: string, fingerprint: LintFingerprint): void;
+/** Drop the lint entry (used when the gate is skipped entirely / nothing to cache). */
+export declare function invalidateLint(projectRoot: string): void;

package/dist/lint-cache.js

@@ -0,0 +1,257 @@
+/**
+ * Persistent cache for the ESLint build gate.
+ *
+ * ESLint is a mandatory correctness gate: it excludes non-AOT code patterns
+ * that the transpiler cannot accept. Running it on every `cuttlefish build`
+ * costs ~3s (38% of a small-project build) and almost always finds nothing on
+ * repeat runs. Its result (zero errors) is a whole-program boolean that
+ * depends only on a small set of inputs, so it is cleanly cacheable.
+ *
+ * Soundness contract:
+ *   - The cache ONLY records a successful (zero-error) lint result.
+ *   - A failing lint never persists (the build aborts anyway).
+ *   - On ANY input change the entry is invalidated and ESLint runs for real.
+ *   - `options.force` and the `CUTTLEFISH_NO_CACHE` env var bypass entirely.
+ *
+ * This mirrors the historical `.cuttlefish-cache.json` timestamp+hash cache
+ * that used to live in this package. It is scoped to the ESLint gate (and the
+ * type-check gate) rather than the transpile-IR pass, because — unlike IR
+ * lowering — these gates' outcomes are whole-program booleans with no
+ * cross-module rehydration requirement.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CACHE_VERSION = 2;
+const DEFAULT_CACHE_NAME = ".cuttlefish-cache.json";
+/** Bypass the cache entirely when set (debugging / CI cold runs). */
+function isCacheDisabled() {
+    return process.env.CUTTLEFISH_NO_CACHE === "1" || process.env.CUTTLEFISH_NO_CACHE === "true";
+}
+/**
+ * Hash a file's content. Returns null if the file cannot be read (treated as
+ * "changed" by callers because the input set is no longer what we recorded).
+ */
+function hashFile(absPath) {
+    try {
+        const content = fs.readFileSync(absPath, "utf8");
+        return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hash size + mtime for a file. Used for inputs (eslint config, eslint package)
+ * that we don't want to fully read on every build, and whose identity is
+ * sufficiently captured by size+mtime. Returns null if the file is missing.
+ */
+function fingerprintStat(absPath) {
+    try {
+        const stat = fs.statSync(absPath);
+        return `${stat.size}:${stat.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Transpiler-self fingerprint: invalidate every cache entry when the
+ * transpiler's own compiled sources change. Mirrors the historical
+ * computeToolchainFingerprint() in incremental-cache.ts.
+ */
+let cachedToolchainFingerprint;
+function computeToolchainFingerprint() {
+    if (cachedToolchainFingerprint !== undefined)
+        return cachedToolchainFingerprint;
+    const candidates = [
+        "transpile.js",
+        "lint-cache.js",
+        "eslint-check.js",
+        path.join("emit", "cpp-emitter.js"),
+        path.join("ir", "build-ir.js"),
+        path.join("ir", "ownership-analysis.js"),
+        path.join("ir", "validation-orchestrator.js"),
+    ];
+    const signature = candidates
+        .map((rel) => path.join(__dirname, rel))
+        .filter((p) => fs.existsSync(p))
+        .map((p) => {
+        const stat = fs.statSync(p);
+        return `${path.basename(p)}:${stat.size}:${stat.mtimeMs}`;
+    })
+        .join("|");
+    cachedToolchainFingerprint = crypto.createHash("sha256").update(signature).digest("hex").slice(0, 16);
+    return cachedToolchainFingerprint;
+}
+/** Resolve the eslint config the same way runEslintCheck does, to avoid drift. */
+export function resolveEslintConfigPath(projectRoot) {
+    const cuttlefishConfig = path.join(projectRoot, ".cuttlefish", "eslint.config.mjs");
+    if (fs.existsSync(cuttlefishConfig))
+        return cuttlefishConfig;
+    for (const name of ["eslint.config.mjs", "eslint.config.js", "eslint.config.cjs"]) {
+        const candidate = path.join(projectRoot, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Resolve the eslint package version that runEslintCheck would load. */
+function resolveEslintIdentity(projectRoot) {
+    const resolvers = [
+        createRequire(path.join(projectRoot, "package.json")),
+        require,
+    ];
+    for (const r of resolvers) {
+        try {
+            const eslintPath = r.resolve("eslint");
+            const pkgPath = r.resolve("eslint/package.json");
+            const version = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version ?? "unknown";
+            return { path: eslintPath, version };
+        }
+        catch {
+            // try next resolver
+        }
+    }
+    return null;
+}
+/** Recursively gather .ts/.tsx/.ui files under a directory (the lint input set). */
+function gatherSourceFiles(srcDir) {
+    const out = [];
+    if (!fs.existsSync(srcDir) || !fs.statSync(srcDir).isDirectory())
+        return out;
+    const stack = [srcDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === "out" || entry.name.startsWith("out-"))
+                    continue;
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                const ext = entry.name.toLowerCase();
+                if (ext.endsWith(".ts") || ext.endsWith(".tsx") || ext.endsWith(".ui")) {
+                    out.push(full);
+                }
+            }
+        }
+    }
+    out.sort();
+    return out;
+}
+export function computeLintFingerprint(projectRoot, srcDir) {
+    const configPath = resolveEslintConfigPath(projectRoot);
+    if (!configPath)
+        return null; // no config => runEslintCheck returns [] without loading eslint
+    const eslint = resolveEslintIdentity(projectRoot);
+    if (!eslint)
+        return null; // eslint unresolvable => runEslintCheck returns []
+    const parts = [];
+    parts.push(["toolchain", computeToolchainFingerprint()]);
+    parts.push(["eslint", `${eslint.version}@${eslint.path}`]);
+    parts.push(["config", `${configPath}:${fingerprintStat(configPath) ?? "missing"}`]);
+    const sources = gatherSourceFiles(srcDir);
+    for (const f of sources) {
+        const h = hashFile(f);
+        parts.push(["src", `${f}:${h ?? "missing"}`]);
+    }
+    const digest = crypto
+        .createHash("sha256")
+        .update(parts.map((p) => p.join("=")).join("\n"))
+        .digest("hex")
+        .slice(0, 32);
+    return { digest, inputs: parts.map((p) => p[1]) };
+}
+function cachePathFor(projectRoot) {
+    return path.join(projectRoot, DEFAULT_CACHE_NAME);
+}
+function loadCacheFile(projectRoot) {
+    const cachePath = cachePathFor(projectRoot);
+    try {
+        if (!fs.existsSync(cachePath))
+            return null;
+        const data = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+        if (data.version === CACHE_VERSION &&
+            data.toolchainFingerprint === computeToolchainFingerprint() &&
+            path.resolve(data.rootDir) === path.resolve(projectRoot)) {
+            return data;
+        }
+    }
+    catch {
+        // Corrupt or unreadable — treat as empty.
+    }
+    return null;
+}
+function saveCacheFile(projectRoot, data) {
+    data.updatedAt = Date.now();
+    try {
+        fs.writeFileSync(cachePathFor(projectRoot), JSON.stringify(data, null, 2), "utf8");
+    }
+    catch {
+        // Non-fatal: caching is best-effort. Next build just re-runs the gate.
+    }
+}
+function freshCacheFile(projectRoot) {
+    return {
+        version: CACHE_VERSION,
+        toolchainFingerprint: computeToolchainFingerprint(),
+        rootDir: path.resolve(projectRoot),
+        gates: {},
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    };
+}
+/**
+ * Decide whether the ESLint gate can be skipped for this project.
+ *
+ * Returns `hit: true` only when:
+ *   - caching is not disabled, not force-bypassed,
+ *   - a fingerprint can be computed (config + eslint resolvable), and
+ *   - the on-disk cache records a success for that exact fingerprint.
+ *
+ * `force` mirrors TranspileOptions.force and bypasses the cache.
+ */
+export function checkLintCache(projectRoot, srcDir, opts = {}) {
+    const fingerprint = computeLintFingerprint(projectRoot, srcDir);
+    if (fingerprint === null)
+        return { hit: false, fingerprint: null };
+    if (opts.force || isCacheDisabled())
+        return { hit: false, fingerprint };
+    const data = loadCacheFile(projectRoot);
+    if (!data)
+        return { hit: false, fingerprint };
+    const entry = data.gates.lint;
+    return { hit: entry?.digest === fingerprint.digest, fingerprint };
+}
+/**
+ * Record a successful ESLint run (zero errors). Never call this after a
+ * failing run — a failing build must not persist a "clean" marker.
+ */
+export function recordLintSuccess(projectRoot, fingerprint) {
+    if (isCacheDisabled())
+        return;
+    const data = loadCacheFile(projectRoot) ?? freshCacheFile(projectRoot);
+    data.gates.lint = { digest: fingerprint.digest, recordedAt: Date.now() };
+    saveCacheFile(projectRoot, data);
+}
+/** Drop the lint entry (used when the gate is skipped entirely / nothing to cache). */
+export function invalidateLint(projectRoot) {
+    const data = loadCacheFile(projectRoot);
+    if (data && data.gates.lint) {
+        delete data.gates.lint;
+        saveCacheFile(projectRoot, data);
+    }
+}

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,22 +159,27 @@ 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-*, and
-            // @typecad/framework-* — these packages ship src/ for HAL metadata
+            // Skip @typecad/board, @typecad/board-*, @typecad/mcu-*, @typecad/hal,
+            // and @typecad/framework-* — these packages ship src/ for HAL metadata
             // introspection (hal-parser.ts, board-resolver.ts) but their source
             // must NOT be transpiled to C++. The HAL resolver loads class/method
             // metadata from these files separately; emitting them as C++ produces
             // thousands of lines of stub functions (board(), gpioWrite(), etc.)
             // and pulls in unsupported types (Promise, variant, Object.freeze).
+            // Skipping @typecad/hal is especially important: its 28 source files
+            // (gpio.ts, i2c.ts, spi.ts, etc.) were all walked through full
+            // buildProgramIR, adding ~40 seconds to every transpile.
             if (moduleSpecifier === "@typecad/board"
+                || moduleSpecifier === "@typecad/hal"
                 || moduleSpecifier.startsWith("@typecad/board-")
                 || moduleSpecifier.startsWith("@typecad/mcu-")
                 || moduleSpecifier.startsWith("@typecad/framework-")) {

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>;
 }

package/dist/platform/generic-strategy.js

@@ -42,10 +42,14 @@ export class GenericStrategy {
     // ── Type normalisation ──────────────────────────────────────────────────
     normalizeCppType(typeName) {
         if (typeName === "auto")
-            return "int";
+            return this.defaultNumericType();
         return typeName;
     }
-    defaultNumericType() { return "int"; }
+    defaultNumericType(compliance) {
+        // A3-9-1: fixed-width integers under AUTOSAR. Legacy 'int' spelling
+        // preserved when autosar is off so default output is byte-identical.
+        return compliance?.isBanned("A3-9-1") ? "int32_t" : "int";
+    }
     mapReturnType(_functionName, returnType) {
         return this.normalizeCppType(returnType);
     }
@@ -185,17 +189,23 @@ export class GenericStrategy {
             helpers.push(asyncRuntime);
         return helpers;
     }
-    asyncLoopInjection(_taskVarNames, configOrBool) {
+    asyncLoopInjection(taskVarNames, configOrBool) {
         let hasPromiseRuntime;
-        if (typeof configOrBool === 'boolean') {
+        if (typeof configOrBool === "boolean") {
             hasPromiseRuntime = configOrBool;
         }
         else {
             hasPromiseRuntime = configOrBool.hasPromiseRuntime;
         }
+        // Drive every async state-machine task once per driver-function iteration.
+        // Task globals auto-start on their first .run() (STATE_0 runs
+        // unconditionally); the state machine no-ops in its terminal/cyclic state.
         const lines = [];
         if (hasPromiseRuntime)
             lines.push("  cuttlefish_pump_microtasks();");
+        for (const n of taskVarNames) {
+            lines.push(`  ${n}.run();`);
+        }
         return lines;
     }
     asyncDriverFunctionName() { return "main"; }
@@ -213,6 +223,9 @@ export class GenericStrategy {
     enumApiGuard(_enumName) { return undefined; }
     getStdLibSupport(_architecture) { return DEFAULT_STDLIB_SUPPORT; }
     // ── Debug code generation ─────────────────────────────────────────────────
+    debugMode(_target) {
+        return 'printf';
+    }
     generateDebugInitCode() {
         return [
             '// === DEBUG: Initialize ===',
@@ -286,4 +299,36 @@ export class GenericStrategy {
             nodeStorage: "flash",
         };
     }
+    // ── HAL (generic fallback) ──────────────────────────────────────────────
+    // The generic/host target has no GPIO or timing hardware. These return
+    // documented no-op stubs so emit stays deterministic rather than throwing
+    // mid-codegen. Host tests that exercise pin-polling paths use a mock
+    // PlatformStrategy (see tests/packages/cuttlefish/async-runtime-static.test.ts).
+    readDigitalPin(_pin) {
+        return "/* gpio unavailable on generic target */ 0";
+    }
+    readAnalogPin(_pin) {
+        return "/* adc unavailable on generic target */ 0";
+    }
+    writeDigitalPin(_pin, _val) {
+        return "/* gpio unavailable on generic target */";
+    }
+    setPinMode(_pin, _mode) {
+        return "/* gpio unavailable on generic target */";
+    }
+    delayMs(_ms) {
+        return "/* delay unavailable on generic target */";
+    }
+    delayMicroseconds(_us) {
+        return "/* delay unavailable on generic target */";
+    }
+    halCallNames() {
+        return new Set();
+    }
+    isHalCall(_name) {
+        return false;
+    }
+    analogReadCallNames() {
+        return new Set();
+    }
 }

package/dist/safety/safety-bridge.d.ts

@@ -0,0 +1,11 @@
+/** Dynamically load @typecad/safety/engine and register the hook.
+ *  Called by transpile.ts at the start of each transpile run.
+ *  Safe to call when @typecad/safety is absent (hook stays null). */
+export declare function loadSafetyEngine(): Promise<void>;
+/** Reset the safety bridge: forget a load was attempted and clear the hook.
+ *  Mirrors resetUIEngine() so each transpile run / test starts clean. */
+export declare function resetSafetyEngine(): void;
+/** Test-only: force the bridge into the "no @typecad/safety" state — mark the
+ *  load as already attempted and leave the hook null, exactly as if the
+ *  dynamic import had failed because the package is not installed. */
+export declare function __simulateSafetyAbsentForTest(): void;

package/dist/safety/safety-bridge.js

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// Safety bridge — loads the safety engine from @typecad/safety and registers it.
+//
+// transpile.ts calls loadSafetyEngine() at the start of transpileFile(). If
+// @typecad/safety is not installed, the import fails gracefully and the hook
+// stays null — cuttlefish works as a pure TS→C++ transpiler with no safety
+// support.
+// ---------------------------------------------------------------------------
+import { setSafetyHook } from "../safety-hook.js";
+let loaded = false;
+/** Dynamically load @typecad/safety/engine and register the hook.
+ *  Called by transpile.ts at the start of each transpile run.
+ *  Safe to call when @typecad/safety is absent (hook stays null). */
+export async function loadSafetyEngine() {
+    if (loaded)
+        return;
+    loaded = true;
+    try {
+        // Dynamic import — @typecad/safety is optional. The module specifier is
+        // routed through a variable (rather than a string literal) so tsc types
+        // the result as `any` and never resolves @typecad/safety's declaration
+        // files while type-checking this file. A literal specifier would make tsc
+        // load safety's dist/engine-index.d.ts, which imports back
+        // @typecad/cuttlefish/safety-hook-types — a self-referencing package path
+        // that resolves into this package's own dist/ output and causes TS5055
+        // ("would overwrite input file") on every rebuild where dist/ exists.
+        const safetyEnginePath = "@typecad/safety/engine";
+        const engine = await import(safetyEnginePath);
+        const hook = engine.registerSafetyEngine();
+        setSafetyHook(hook);
+    }
+    catch {
+        // @typecad/safety is not installed — cuttlefish works without safety.
+    }
+}
+/** Reset the safety bridge: forget a load was attempted and clear the hook.
+ *  Mirrors resetUIEngine() so each transpile run / test starts clean. */
+export function resetSafetyEngine() {
+    loaded = false;
+    setSafetyHook(null);
+}
+/** Test-only: force the bridge into the "no @typecad/safety" state — mark the
+ *  load as already attempted and leave the hook null, exactly as if the
+ *  dynamic import had failed because the package is not installed. */
+export function __simulateSafetyAbsentForTest() {
+    loaded = true;
+    setSafetyHook(null);
+}

package/dist/safety/sidecar-bridge.d.ts

@@ -0,0 +1,5 @@
+import type { SafetyMetadata } from "../safety-hook.js";
+/** Dynamically import the safety package's sidecar renderer.
+ *  Uses a variable-held specifier so tsc doesn't try to resolve the
+ *  @typecad/safety types at build time (avoids circular dependency). */
+export declare function renderSafetySidecar(metadata: SafetyMetadata, toolVersion: string): Promise<string>;

package/dist/safety/sidecar-bridge.js

@@ -0,0 +1,22 @@
+/** Dynamically import the safety package's sidecar renderer.
+ *  Uses a variable-held specifier so tsc doesn't try to resolve the
+ *  @typecad/safety types at build time (avoids circular dependency). */
+export async function renderSafetySidecar(metadata, toolVersion) {
+    const spec = "@typecad/safety/iso26262/sidecar-writer";
+    try {
+        const mod = await import(spec);
+        return mod.renderSafetySidecar(metadata, toolVersion);
+    }
+    catch {
+        // Fallback: inline the renderer so the sidecar is produced even if
+        // the subpath export isn't configured.
+        return JSON.stringify({
+            schemaVersion: "1.0.0",
+            standard: "ISO 26262 Part 6",
+            tool: "cuttlefish (@typecad/safety)",
+            toolVersion,
+            generatedAt: new Date().toISOString(),
+            safetyFunctions: metadata.functions,
+        }, null, 2);
+    }
+}