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

package/dist/install/handle-install.js

@@ -0,0 +1,177 @@
+// `cuttlefish install` — installs a chosen @typecad/framework-* package into the
+// current project. The flow asks which board to target first, then narrows the
+// framework choices to those compatible with that board (see framework-catalog).
+// A framework id may be passed directly (`cuttlefish install arduino`) to skip
+// the prompts entirely, which also makes the command usable in CI.
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { spawnSync } from "node:child_process";
+import chalk from "chalk";
+import { KNOWN_TARGETS } from "../create/index.js";
+import { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";
+// ── prompts (mirror the create wizard's style for a consistent UX) ──────────
+async function promptSelect(rl, prompt, options) {
+    console.log(`${chalk.cyan("?")} ${prompt}:`);
+    for (let i = 0; i < options.length; i++) {
+        console.log(`  ${chalk.dim(`${i + 1})`)} ${options[i].label}`);
+    }
+    while (true) {
+        const answer = await rl.question(`  Enter number (1-${options.length}): `);
+        const idx = parseInt(answer.trim(), 10) - 1;
+        if (idx >= 0 && idx < options.length) {
+            return options[idx].value;
+        }
+        console.log(`  ${chalk.red("✗")} Please enter a number between 1 and ${options.length}.`);
+    }
+}
+async function selectBoardInteractively(rl) {
+    const options = KNOWN_TARGETS.map((t) => ({
+        label: t.isNative
+            ? `${t.displayName} (Windows/Linux executable)`
+            : `${t.displayName} (${t.architecture.toUpperCase()})`,
+        value: t.id,
+    }));
+    const selectedId = await promptSelect(rl, "Target board", options);
+    return KNOWN_TARGETS.find((t) => t.id === selectedId);
+}
+/**
+ * Pick a framework for `target`. When only one framework is compatible with the
+ * board it is auto-selected (mirrors the create wizard's single-option path) so
+ * the user isn't asked a question with one answer.
+ */
+async function selectFrameworkInteractively(rl, target, compatible) {
+    if (compatible.length === 1) {
+        const only = compatible[0];
+        console.log(`${chalk.cyan("?")} Framework: ${chalk.white(only.label)} ${chalk.dim(`(only option for ${target.id})`)}`);
+        return only;
+    }
+    const selectedId = await promptSelect(rl, "Framework", compatible.map((f) => ({ label: f.label, value: f.id })));
+    return compatible.find((f) => f.id === selectedId);
+}
+let testRunner;
+/**
+ * FOR TESTS ONLY. Replaces the real spawn-based installer with `runner`.
+ * Pass `undefined` to restore the real executor.
+ */
+export function __setInstallRunnerForTest(runner) {
+    testRunner = runner;
+}
+function runRealInstall(cmd) {
+    // stdio: "inherit" streams the package manager's own output to the terminal
+    // (install progress, deprecation warnings, etc.). On failure the user has
+    // already seen the details above, so we only need to report the exit code.
+    const result = spawnSync(cmd.bin, cmd.args, {
+        cwd: cmd.cwd,
+        stdio: "inherit",
+    });
+    if (result.error) {
+        const errno = result.error.code;
+        return {
+            status: null,
+            launchError: errno === "ENOENT" ? `'${cmd.bin}' not found on PATH` : String(result.error),
+        };
+    }
+    return { status: result.status };
+}
+/**
+ * Resolve the package manager and run the install for `entry`'s package. In
+ * dry-run mode the command is printed but not executed. Throws on launch
+ * failure or non-zero exit so the CLI surfaces a clear error.
+ */
+export function installFrameworkPackage(entry, opts) {
+    const pm = detectPackageManager(opts.cwd);
+    const { bin, args } = buildInstallCommand(pm, entry.packageName);
+    if (opts.dryRun) {
+        console.log(`${chalk.cyan("$")} ${bin} ${args.join(" ")}`);
+        return { pm, bin, args };
+    }
+    const cmd = { bin, args, cwd: opts.cwd };
+    const run = testRunner ?? runRealInstall;
+    const result = run(cmd);
+    if (result.launchError) {
+        throw new Error(`Failed to run '${bin}': ${result.launchError}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`'${bin} ${args.join(" ")}' exited with code ${result.status}. See the package manager output above for details.`);
+    }
+    return { pm, bin, args };
+}
+// ── command entry point ─────────────────────────────────────────────────────
+export async function handleInstall(options) {
+    const cwd = process.cwd();
+    // 1. Resolve which framework to install.
+    let entry;
+    if (options.framework) {
+        const resolved = frameworkCatalogEntry(options.framework);
+        if (!resolved) {
+            const available = FRAMEWORK_CATALOG.filter((f) => f.installable).map((f) => f.id).join(", ");
+            throw new Error(`Unknown framework '${options.framework}'. Available: ${available}`);
+        }
+        if (!resolved.installable) {
+            throw new Error(`Framework '${options.framework}' has no published package yet and cannot be installed.`);
+        }
+        entry = resolved;
+        console.log(`${chalk.cyan("?")} Framework: ${chalk.white(entry.label)}`);
+    }
+    else {
+        // Resolve the target board. --board skips the board prompt; otherwise the
+        // board is chosen interactively (which requires a TTY — handled below).
+        let target;
+        if (options.board) {
+            const found = KNOWN_TARGETS.find((t) => t.id === options.board);
+            if (!found) {
+                const available = KNOWN_TARGETS.map((t) => t.id).join(", ");
+                throw new Error(`Unknown board '${options.board}'. Available: ${available}`);
+            }
+            target = found;
+            console.log(`${chalk.cyan("?")} Board: ${chalk.white(target.displayName)} (${chalk.dim(target.id)})`);
+        }
+        // Narrow to the frameworks compatible with that board.
+        let compatible;
+        if (target) {
+            compatible = frameworksForTarget(target).filter((f) => f.installable);
+            if (compatible.length === 0) {
+                throw new Error(`No installable frameworks are compatible with board '${target.id}'.`);
+            }
+        }
+        if (compatible && compatible.length === 1) {
+            // Only one framework fits this board — auto-select it (no prompt, so this
+            // path also works under CI / non-interactive stdin).
+            entry = compatible[0];
+            console.log(`${chalk.cyan("?")} Framework: ${chalk.white(entry.label)} ${chalk.dim(`(only option for ${target.id})`)}`);
+        }
+        else {
+            // Need to prompt — for the board (if --board wasn't given) and/or for the
+            // framework (when 2+ are compatible). Refuse to hang on a readline that
+            // can't be answered (e.g. piped stdin under CI).
+            if (!process.stdin.isTTY) {
+                throw new Error("No framework specified and stdin is not interactive. " +
+                    "Pass a framework id (e.g. 'cuttlefish install arduino'), " +
+                    "or a board with a single compatible framework (e.g. '--board arduino-uno').");
+            }
+            const rl = readline.createInterface({ input, output });
+            try {
+                if (!target) {
+                    target = await selectBoardInteractively(rl);
+                    compatible = frameworksForTarget(target).filter((f) => f.installable);
+                    if (compatible.length === 0) {
+                        throw new Error(`No installable frameworks are compatible with board '${target.id}'.`);
+                    }
+                }
+                entry = await selectFrameworkInteractively(rl, target, compatible);
+            }
+            finally {
+                rl.close();
+            }
+        }
+    }
+    // 2. Install it.
+    console.log(`\n${chalk.cyan("⤳")} Installing ${chalk.white(entry.packageName)} into ${chalk.dim(cwd)}…`);
+    const result = installFrameworkPackage(entry, { cwd, dryRun: options.dryRun });
+    if (options.dryRun) {
+        console.log(chalk.dim("(dry-run — nothing was installed)"));
+        return;
+    }
+    console.log(`\n${chalk.green("✓")} Installed ${chalk.white(entry.packageName)} via ${result.pm}.`);
+    console.log(chalk.dim(`Next: run 'cuttlefish create' and pick ${entry.id}, or set framework: "${entry.packageName}" in cuttlefish.config.ts.`));
+}

package/dist/install/index.d.ts

@@ -0,0 +1,4 @@
+export { handleInstall, installFrameworkPackage, __setInstallRunnerForTest } from "./handle-install.js";
+export type { InstallResult } from "./handle-install.js";
+export { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";
+export type { FrameworkCatalogEntry, BoardLike, PackageManager, } from "./framework-catalog.js";

package/dist/install/index.js

@@ -0,0 +1,3 @@
+// `cuttlefish install` command — install a @typecad/framework-* package.
+export { handleInstall, installFrameworkPackage, __setInstallRunnerForTest } from "./handle-install.js";
+export { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";

package/dist/ir/adc-range-validation.js

@@ -4,6 +4,7 @@
 // Detects comparisons against analogRead() values that exceed the board's
 // ADC resolution (e.g., comparing to > 1023 on a 10-bit Arduino Uno).
 // ---------------------------------------------------------------------------
+import { hasLoadedFramework, getLoadedFramework } from '../framework-registry.js';
 /**
  * Get ADC configuration from board constants.
  */
@@ -41,7 +42,19 @@ function isAnalogRead(expr) {
         return op === 'adc.read' || op === 'adc.read_voltage';
     }
     if (expr.kind === 'raw') {
-        return /analogRead\s*\(/.test(expr.value);
+        const value = expr.value;
+        // Ask the loaded framework which call names produce an ADC read; fall back
+        // to the Wiring-derived analogRead when no framework is loaded.
+        const frameworkNames = hasLoadedFramework()
+            ? getLoadedFramework().strategy.analogReadCallNames?.()
+            : undefined;
+        const names = frameworkNames ?? new Set(['analogRead']);
+        for (const name of names) {
+            const re = new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\(`);
+            if (re.test(value))
+                return true;
+        }
+        return false;
     }
     return false;
 }

package/dist/ir/build-ir-state.d.ts

@@ -78,6 +78,7 @@ export declare class CompilationContext {
     floatVariables: Set<string>;
     snprintfCounter: number;
     callbackPlaceholderCounter: number;
+    bleCharCounter: number;
     activeStrategy: PlatformStrategy | null;
     restParamFunctions: Map<string, string>;
     /**

package/dist/ir/build-ir-state.js

@@ -65,6 +65,12 @@ export class CompilationContext {
         this.floatVariables = new Set();
         this.snprintfCounter = 0;
         this.callbackPlaceholderCounter = 0;
+        // BLE characteristic index counter — persists across separate Ble.server()
+        // calls so a multi-characteristic server (one server() per char, the common
+        // ble-demo pattern) gets unique sequential indices instead of every char
+        // clobbering slot 0. Read by the server()/characteristic() resolver branches
+        // in hal-parser.ts. Reset per file in hal-emitter.ts with the other counters.
+        this.bleCharCounter = 0;
         this.activeStrategy = null;
         this.restParamFunctions = new Map();
         /**
@@ -246,6 +252,14 @@ export function setCurrentBoardConstants(v) {
                 pinAliasMap.set(name, num);
                 mcuPinForwardMap.set(name, num);
                 mcuPinReverseMap.set(num, name);
+                // Register an identifier-safe variant so that pins whose canonical
+                // name is not a legal JS identifier (e.g. nRF52840 "P0.28") can be
+                // imported under their underscore form (P0_28). See "Pin Naming
+                // Conventions" in the root AGENTS.md.
+                const identName = name.replace(/[.\s-]/g, "_");
+                if (identName !== name) {
+                    pinAliasMap.set(identName, num);
+                }
             }
         }
     }

package/dist/ir/build-ir.js

@@ -443,14 +443,14 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
                         }
                     }
                 }
-                // Track HAL instances imported from board packages and framework stubs
-                // so the HAL resolver can resolve them to Arduino C++ names.
+                // Track HAL instances imported from board packages and framework HAL
+                // subpaths so the HAL resolver can resolve them to framework C++ names.
                 // The `@typecad/board` virtual import resolves to the board package, so it
                 // also registers pin aliases (LED, etc.). Case-insensitive on the scope.
                 const lowerSpecifier = moduleSpecifier.toLowerCase();
                 const isHALSource = lowerSpecifier.startsWith('@typecad/board-')
-                    || lowerSpecifier === '@typecad/framework-arduino/arduino'
-                    || lowerSpecifier === '@typecad/board';
+                    || lowerSpecifier === '@typecad/board'
+                    || /^@typecad\/framework-[a-z0-9-]+\/(arduino|hal|gpio)$/.test(lowerSpecifier);
                 // UI authoring namespace: `import { ui } from "@typecad/ui"`. The `ui`
                 // value is a compile-time construct (its calls are intercepted by
                 // tryResolveUICall); it must NOT be emitted as a C++ struct/value.

package/dist/ir/call-graph.js

@@ -159,6 +159,22 @@ export function buildCallGraph(program) {
             }
         }
     }
+    // Registered callbacks from the HAL resolver (e.g. the arrow function passed
+    // to `Ble.characteristic(...).onRead(() => readTemp())`) are NOT present in
+    // top-level statements — they ride in `program.registeredCallbacks` and are
+    // later hoisted to file-scope `*_isr_*` functions by top-level-prep. The
+    // placeholder name (`__CALLBACK_N__`) is what surfaces in top-level deps,
+    // not the identifiers the callback body references (e.g. a free function
+    // like `readTemp`). Without this scan those references are invisible to the
+    // call graph: the function survives the hoist (its call sits inside the
+    // emitted ISR) but is tree-shaken as unreachable, and g++ later reports it
+    // "not declared in this scope". Attach their body identifiers to
+    // __top_level__ since the callbacks execute from the top-level entry path.
+    for (const rc of (program.registeredCallbacks ?? [])) {
+        for (const id of collectExpressionIdentifiers(rc.callbackIR)) {
+            topLevelDependencies.add(id);
+        }
+    }
     nodes.set("__top_level__", {
         name: "__top_level__",
         kind: "variable",

package/dist/ir/expression-to-ir.js

@@ -12,6 +12,7 @@ import { tryLowerRegisterRead } from "./transformers/register-assignment.js";
 import { tryLowerArrayAndStringMethods } from "./transformers/array-methods.js";
 import { collectReturns, inferExprCppType, typeNodeToCppType } from "./type-resolution.js";
 import { parseCppType, elementOf, renderCppType, bareType, parsedIsPointer, parsedIsVector, parsedIsMap, parsedIsSet, parsedIsTuple, parsedIsStdString, parsedElementString, parsedBareString, isContainer } from "../api/shared/cpp-type-ir.js";
+import { hasSafetyHook, requireSafetyHook } from "../safety-hook.js";
 function resolveExprCppType(expr) {
     if (ts.isNonNullExpression(expr) || ts.isParenthesizedExpression(expr)) {
         return resolveExprCppType(expr.expression);
@@ -184,6 +185,143 @@ function resolveCallReturnTypeForNullGuard(call, sourceText) {
     }
     return undefined;
 }
+/** The SafeReadResult/SafeWriteResult chain methods whose lambda args must
+ *  render inline (preserving closure captures). Detected on the TS chain to
+ *  decide whether to take the structured-receiver path. */
+const SAFETY_RESULT_CHAIN_METHODS = new Set(["ok", "fail", "fault", "always"]);
+/** Detect `safe.<read|write>(...).<ok|fail|fault|always>(handler)...` chains
+ *  and build them as nested method-call IR nodes with a STRUCTURED receiverExpr
+ *  (not a flattened callee string). This preserves inner lambda args so the
+ *  emit pipeline can render them inline via renderLambda.
+ *
+ *  Returns null when the expression is not a safe.* call chained with at least
+ *  one result method (terminal safe.read/safe.write are handled by the
+ *  statement/var-decl interceptors; non-safe chains use the generic path). */
+function tryResolveSafetyChain(expr, sourceText, diagnostics, pointerVars) {
+    if (!hasSafetyHook())
+        return null;
+    const chain = [];
+    let cur = expr;
+    while (ts.isCallExpression(cur) && ts.isPropertyAccessExpression(cur.expression)) {
+        chain.push({ methodName: cur.expression.name.text, callNode: cur });
+        cur = cur.expression.expression;
+    }
+    // After the loop, `cur` is the innermost receiver. For a safe.* chain, the
+    // last-pushed chain element is the safe.read/safe.write root (its
+    // callNode.expression.expression is the identifier `safe`). Identify it.
+    if (chain.length === 0)
+        return null;
+    const root = chain[chain.length - 1];
+    const rootCall = root.callNode;
+    // rootCall.expression is `safe.read` (PropertyAccess); rootCall.expression.expression
+    // must be the identifier `safe` for this to be a safe.* root.
+    // The root method is read/write; the links above it (chain[0..length-2]) must
+    // include at least one result-chain method (ok/fail/fault/always).
+    const resultLinks = chain.slice(0, chain.length - 1);
+    const hasChainMethod = resultLinks.some((link) => SAFETY_RESULT_CHAIN_METHODS.has(link.methodName));
+    if (!hasChainMethod)
+        return null;
+    // Resolve the safe.<method>(...) root to a hal-expr (the same way variables.ts
+    // does for `const r = safe.read(pin)`). This becomes the innermost receiver.
+    const rootPropAccess = rootCall.expression;
+    const safeMethod = rootPropAccess.name.text;
+    const argValues = rootCall.arguments.map((a) => {
+        if (ts.isNumericLiteral(a))
+            return Number(a.text);
+        if (ts.isStringLiteral(a))
+            return a.text;
+        if (a.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (a.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+        if (ts.isIdentifier(a))
+            return a.text;
+        return a.getText();
+    });
+    const op = requireSafetyHook().resolveSemanticCall?.(`safe.${safeMethod}`, argValues);
+    // If the hook couldn't resolve the pin (halInstances not yet populated for
+    // this identifier at this point in IR building), fall back to rendering the
+    // root verbatim. The chain structure (with inline lambdas) is still correct;
+    // only the root's HAL resolution is deferred. This happens for multi-link
+    // chains where the resolver runs before the pin's HAL instance is registered.
+    let receiver;
+    if (op) {
+        receiver = { kind: "hal-expr", operation: op };
+    }
+    else {
+        // Best-effort: resolve the pin number directly from halInstances (the hook's
+        // resolvePinArg does the same lookup, but calling it directly here avoids the
+        // hook's early-return on unresolved pins).
+        const pinArg = argValues[0];
+        let pinNum;
+        if (typeof pinArg === "string") {
+            const inst = halInstances.get(pinArg);
+            if (inst) {
+                const pv = inst.fieldValues.get("_pin") ?? inst.fieldValues.get("pin");
+                if (pv !== undefined)
+                    pinNum = Number(pv);
+            }
+        }
+        else if (typeof pinArg === "number") {
+            pinNum = pinArg;
+        }
+        if (pinNum !== undefined) {
+            // Build the op manually now that we have the pin.
+            const fallbackOp = safeMethod === "read"
+                ? { operation: "safety.read_safe", pin: pinNum }
+                : { operation: "safety.write_verify", pin: pinNum, value: argValues[1] ?? 0 };
+            receiver = { kind: "hal-expr", operation: fallbackOp };
+        }
+        else {
+            // Last resort: verbatim text. The chain renders but the root won't have
+            // resolved to __tc_safety::read_safe — acceptable degradation.
+            receiver = { kind: "raw", value: rootCall.getText() };
+        }
+    }
+    // The root renders as __tc_safety::read_safe(pin) — render it to text so the
+    // callee string (used for non-receiverExpr consumers like type inference) is
+    // correct.
+    const rootText = renderExprAsText(receiver);
+    // Build nested method-call nodes bottom-up over the RESULT links only
+    // (chain[0..length-2], excluding the root at chain[length-1]). chain[0] is the
+    // outermost call (e.g. .fail); we build from the innermost result link outward.
+    for (let i = resultLinks.length - 1; i >= 0; i--) {
+        const link = resultLinks[i];
+        // Render this link's args as IR (lambdas become lambda IR nodes that
+        // renderLambda handles at emit time).
+        const argIRs = link.callNode.arguments.map((a) => expressionToIR(a, sourceText, diagnostics, pointerVars));
+        // Set concrete param types on lambda args so renderLambda emits
+        // `const SafeReadResult& r` instead of `auto r`. Generic lambdas (auto
+        // params) require C++14; AVR's gnu++11 doesn't support them. The chain
+        // knows the result type from the root (read -> SafeReadResult,
+        // write -> SafeWriteResult).
+        const resultType = safeMethod === "read" ? "SafeReadResult" : "SafeWriteResult";
+        for (const argIR of argIRs) {
+            if (argIR.kind === "lambda" && argIR.params) {
+                for (const p of argIR.params) {
+                    if (!p.cppType || p.cppType === "auto") {
+                        p.cppType = `const ${resultType}&`;
+                    }
+                }
+            }
+        }
+        // Build a callee string for backward-compat with consumers that read
+        // method-call.callee. The receiver text is rootText for the innermost link,
+        // or the prior receiver's rendered text for outer links.
+        const priorCallee = i === resultLinks.length - 1
+            ? rootText
+            : renderExprAsText(receiver);
+        const callee = `${priorCallee}.${escapeCppKeyword(link.methodName, new Set())}`;
+        receiver = {
+            kind: "method-call",
+            callee,
+            args: argIRs,
+            methodName: link.methodName,
+            receiverExpr: receiver,
+        };
+    }
+    return receiver;
+}
 export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new Map()) {
     function emitUnsupportedExpression(message) {
         diagnostics.push(makeDiagnostic(sourceText, expr.pos, message, "error", "TS2CPP_UNSUPPORTED_EXPR"));
@@ -953,6 +1091,18 @@ export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new
         };
     }
     if (ts.isCallExpression(expr)) {
+        // ---- safe.read/safe.write chained with .ok/.fail/.fault/.always ----
+        // Method chains like `safe.read(pin).ok(r => {...}).fail(r => {...})` cannot
+        // use the generic method-call builder because it flattens the receiver into
+        // a callee STRING (expression-to-ir.ts ~line 1475), destroying inner lambda
+        // args (they become `/* __lambda__ */` placeholders baked into the callee
+        // text). This resolver detects a safe.* call followed by a chain of fluent
+        // result methods and builds it bottom-up as nested method-call nodes with a
+        // STRUCTURED receiverExpr, so the emit pipeline renders each lambda arg
+        // inline via renderLambda (preserving closure captures).
+        const safetyChain = tryResolveSafetyChain(expr, sourceText, diagnostics, pointerVars);
+        if (safetyChain)
+            return safetyChain;
         // ---- rawCppExpr() — compile-time C++ injection in expression context ----
         // Mirrors the statement-position rawCpp()/__EMIT__ path, but emits the raw
         // text as an expression (e.g. for IDF macros like WIFI_INIT_CONFIG_DEFAULT()

package/dist/ir/function-builder.js

@@ -163,6 +163,7 @@ export function functionDeclarationToIR(node, fileName, sourceText, diagnostics,
         const elementType = restParam.cppType.replace(/^(?:const\s+)?std::vector<(.+)>&?$/, "$1");
         restParamFunctions.set(node.name.text, elementType);
     }
+    const fnDecorators = extractAsilFromComments(node, sourceText);
     return {
         originalName: node.name.text,
         isAsync,
@@ -174,8 +175,29 @@ export function functionDeclarationToIR(node, fileName, sourceText, diagnostics,
         ...(fnTypeParams && fnTypeParams.length > 0 ? { typeParameters: fnTypeParams } : {}),
         ...(isGenerator ? { isGenerator: true } : {}),
         ...(isExported ? { isExported: true } : {}),
+        ...(fnDecorators && fnDecorators.length > 0 ? { decorators: fnDecorators } : {}),
     };
 }
+/** Extract ASIL annotations from leading comments (e.g. `// @asilD`).
+ *
+ *  Uses comment-based annotations instead of TypeScript decorators because
+ *  TS decorators on function declarations produce TS1206 errors in the VS Code
+ *  language server and the @typescript-eslint/parser (both reject decorators
+ *  on functions — only class/method/property decorators are supported).
+ *  Comment annotations are valid TypeScript in any context, any editor, and
+ *  any toolchain — no false-positive errors. */
+function extractAsilFromComments(node, sourceText) {
+    const comments = extractNodeComments(node, sourceText);
+    const names = [];
+    for (const comment of comments.leadingComments) {
+        // Match `// @asilD`, `// @asilC`, `// @asilB`, `// @asilA`, `// @asilQM`
+        const match = comment.match(/@(asil[DCBAQM])/i);
+        if (match) {
+            names.push(match[1]);
+        }
+    }
+    return names.length > 0 ? names : undefined;
+}
 export function variableAsFunctionToIR(node, fileName, sourceText, diagnostics, functionReturnTypes, typeAliasNodes, boilerplates, pointerVars = new Map(), lowerStatementList) {
     const functionExpressionDeclarations = node.declarationList.declarations.filter((declaration) => {
         if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {

package/dist/ir/hal/hal-emitter.js

@@ -55,16 +55,16 @@ function prefixOperatorText(operator) {
  * keeps `this` out of the emitted free function. Returns null if the method
  * is not a recognized inlinable getter.
  */
-function inlineThisGetterCall(methodName, pin) {
+function inlineThisGetterCall(methodName, pin, strategy) {
     switch (methodName) {
         case "read":
-            return `digitalRead(${pin})`;
+            return strategy?.readDigitalPin?.(pin) ?? `digitalRead(${pin})`;
         case "readAnalog":
-            return `analogRead(${pin})`;
+            return strategy?.readAnalogPin?.(pin) ?? `analogRead(${pin})`;
         case "isHigh":
-            return `digitalRead(${pin})`;
+            return strategy?.readDigitalPin?.(pin) ?? `digitalRead(${pin})`;
         case "isLow":
-            return `(!digitalRead(${pin}))`;
+            return strategy?.readDigitalPin ? `(!${strategy.readDigitalPin(pin)})` : `(!digitalRead(${pin}))`;
         default:
             return null;
     }
@@ -200,7 +200,7 @@ export function resolveExpressionText(expr, instance, paramNames, callArgTexts,
                 const methodName = expr.expression.name.text;
                 const pin = instance.fieldValues.get("_pin") ?? instance.fieldValues.get("pin");
                 if (pin !== undefined) {
-                    const inlined = inlineThisGetterCall(methodName, pin);
+                    const inlined = inlineThisGetterCall(methodName, pin, getContext().activeStrategy);
                     if (inlined !== null)
                         return inlined;
                 }
@@ -633,6 +633,10 @@ export function resetHALResolver() {
     floatVariables.clear();
     getContext().callbackPlaceholderCounter = 0;
     getContext().snprintfCounter = 0;
+    // Reset the BLE characteristic counter so each file's GATT table starts at
+    // index 0. Without this, a second transpile in one process would continue
+    // from the previous file's counter and emit offset indices.
+    getContext().bleCharCounter = 0;
 }
 /** Resolve a hal-expr IR node to its C++ text using the active strategy. */
 export function setActiveStrategy(strategy) {

package/dist/ir/hal/hal-parser.js

@@ -378,12 +378,16 @@ export function resolveHALReceiver(receiver) {
                 }
                 // Specialized handling for BLE factory chaining
                 // (Ble.server(name).characteristic(uuid,type,perms).onRead(handler)):
-                // server() creates a BleServer with _name, _charCount from a global
-                // counter (persists across separate server() calls so multi-char
-                // servers get unique indices), _svcCount=1.
-                // characteristic() reads _charCount for the add_char call,
-                // then sets _lastChar=_charCount and increments _charCount so the next
-                // characteristic gets the next slot. onRead/onWrite read _lastChar.
+                // server() creates a BleServer. The characteristic index is taken from a
+                // per-file counter (bleCharCounter on CompilationContext) that persists
+                // across separate server() calls so a multi-characteristic server — the
+                // common ble-demo pattern of one Ble.server(name).characteristic(...) per
+                // char — gets unique sequential indices (0,1,2,…) instead of every char
+                // landing on slot 0 and clobbering the previous on_read/on_write handler.
+                // characteristic() reads the current counter for the add_char call and
+                // posts-increments it so the next characteristic gets the next slot.
+                // onRead/onWrite/onNotify carry _lastChar (the slot characteristic() just
+                // reserved). The counter resets per file in hal-emitter.ts.
                 if (innerInstance.className === "BleClass" && methodName === "server" && receiver.arguments.length > 0) {
                     const nameText = httpUrlArgText(receiver.arguments[0]);
                     if (nameText) {
@@ -394,9 +398,12 @@ export function resolveHALReceiver(receiver) {
                     }
                 }
                 if (innerInstance.className === "BleServer" && methodName === "characteristic") {
-                    // characteristic(uuid, type, perms) returns this (BleServer).
-                    // The C++ shim auto-assigns the char index at runtime via
-                    // __tc_ble.current_char, so the resolver doesn't need to track indices.
+                    // characteristic(uuid, type, perms) returns this (BleServer). The
+                    // characteristic index is assigned centrally in the bleAddChar plugin
+                    // (hal-plugins.ts) from a per-file counter — see the note there for
+                    // why this can't be done via instance fieldValues (resolveHALReceiver
+                    // re-resolves the receiver for each chain level and would drop a
+                    // value stamped here).
                     return innerInstance;
                 }
                 if (innerInstance.className === "BleServer" && methodName === "service") {