@typecad/cuttlefish 1.0.0-alpha.14 → 1.0.0-alpha.15

package/dist/orchestrator/type-checker.d.ts

@@ -22,11 +22,11 @@ export interface TypeCheckResult {
  * Returns early if any errors are found.
  *
  * @param files List of TypeScript files to type-check
- * @param _boardPackage Optional board package for resolving @typecad/board imports
- * @param entryFile Entrypoint sketch/main file
+ * @param _boardTarget Optional board package for resolving @typecad/board imports
+ * @param entryFile Entrypoint source/main file
  * @returns TypeCheckResult with success status and any error messages
  */
-export declare function typeCheckFiles(files: string[], _boardPackage?: string, entryFile?: string): TypeCheckResult;
+export declare function typeCheckFiles(files: string[], _boardTarget?: string, entryFile?: string): TypeCheckResult;
 /**
  * Run semantic gates against the user files of a type-checked program.
  *

package/dist/orchestrator/type-checker.js

@@ -10,11 +10,11 @@ import { requireUIHook, hasUIHook } from "../ui-hook.js";
  * Returns early if any errors are found.
  *
  * @param files List of TypeScript files to type-check
- * @param _boardPackage Optional board package for resolving @typecad/board imports
- * @param entryFile Entrypoint sketch/main file
+ * @param _boardTarget Optional board package for resolving @typecad/board imports
+ * @param entryFile Entrypoint source/main file
  * @returns TypeCheckResult with success status and any error messages
  */
-export function typeCheckFiles(files, _boardPackage, entryFile) {
+export function typeCheckFiles(files, _boardTarget, entryFile) {
     // Find the nearest tsconfig.json by walking up from the entry file (preferred)
     // or the first file in the graph. Using the entry file ensures we pick up the
     // user's tsconfig (with path mappings) rather than a dependency's tsconfig.

package/dist/platform/async-runtime.js

@@ -16,7 +16,7 @@ export function buildAsyncRuntimePolyfill(program, ctx, target, queueCapacity, s
     // instead of a millis() token the generic target never defines). When the
     // expression uses std::chrono, the polyfill must carry <chrono> itself —
     // the generic strategy's forcedIncludes are empty by design.
-    const now = strategy?.currentTimeMillis?.() ?? "millis()";
+    const now = strategy?.currentTimeMillis?.() ?? "__tc_now_ms()";
     const requiredIncludes = ["<functional>", "<vector>", "<utility>", "<string>"];
     if (now.includes("std::chrono"))
         requiredIncludes.push("<chrono>");

package/dist/platform/coop-scheduler-runtime.js

@@ -14,14 +14,14 @@ import { generateCoopScheduler } from "../api/shared/index.js";
  * links on minimal-libc targets (Zephyr) where the std::function Promise
  * runtime does not.
  */
-export function buildCoopSchedulerPolyfill(_program, config, currentTimeExpr = "millis()") {
+export function buildCoopSchedulerPolyfill(_program, config, currentTimeExpr = "__tc_now_ms()") {
     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() /
+        // STL-free: only needs a 32-bit unsigned time source (__tc_now_ms() /
         // k_uptime_get_32()) and fixed-width types, both available everywhere.
         requiredIncludes: [],
         forwardDeclarations: [],

package/dist/platform/generic-debug-codegen.d.ts

@@ -0,0 +1,36 @@
+export interface CapturedVariable {
+    name: string;
+    isFunction?: boolean;
+    /** Coarse C++ type category (inferred by the preprocessor without a checker). */
+    cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
+}
+export interface LogMessagePart {
+    type: 'text' | 'variable';
+    value: string;
+}
+/**
+ * Generate the debug-mode banner. The host console needs no setup, but the
+ * printf/getchar calls below need <cstdio>: include() registers it on the
+ * program (the generic strategy's forcedIncludes is deliberately empty), and
+ * the strategy-side usesCstdio gates (e.g. native) also pick the banner up
+ * from the rawCpp text.
+ */
+export declare function generateGenericInitCode(): string[];
+/**
+ * Generate generic/native code for a breakpoint.
+ *
+ * The halt reads stdin until ENTER; any 's' typed before it marks this
+ * breakpoint skipped for the rest of the run. The flag is a C++ static local
+ * inside the emitted block (safe here — unlike TS-injected declarations, the
+ * rawCpp text bypasses the TS parser entirely), so the skip persists across
+ * loop() iterations. EOF on stdin exits the halt instead of spinning.
+ *
+ * When `breakpointId` is set the whole block is guarded by that flag; the
+ * preprocessor assigns ids to every halting breakpoint.
+ */
+export declare function generateGenericBreakpointCode(fileName: string, lineNum: number, originalLine: string, variables: CapturedVariable[], normalizedCondition: string | undefined, breakpointId?: number): string[];
+/**
+ * Generate generic/native code for a logpoint (logs a message without
+ * halting). Each part is its own printf, then a newline.
+ */
+export declare function generateGenericLogpointCode(fileName: string, lineNum: number, parts: LogMessagePart[], variables: CapturedVariable[]): string[];

package/dist/platform/generic-debug-codegen.js

@@ -0,0 +1,185 @@
+// ---------------------------------------------------------------------------
+// Generic/native debug code generator — printf-based debug output
+//
+// The debug preprocessor injects these lines into the user's TypeScript, so
+// every injected line must be TS-parseable AND lower faithfully. Raw C++ in
+// an injected line does not survive: the TS parser reads `std::cout << ...`
+// as a label plus garbage, and the emitted C++ was `std: :` noise that could
+// never compile. Every line therefore rides the rawCpp() passthrough — the
+// call lowers to __EMIT__ and its string argument is emitted as verbatim
+// C++ — so the generator can author arbitrary C++ (printf, static_cast,
+// the static skip flag) without the TS parser ever seeing it.
+//
+// printf/getchar need <cstdio>: program-analysis marks usesCstdio from
+// __EMIT__ string arguments, and the native/generic forcedIncludes gate
+// <cstdio> on that flag.
+//
+// Used by GenericStrategy's generateDebug* overrides (the debug preprocessor
+// falls back to GenericStrategy for every framework whose strategy does not
+// define its own codegen — e.g. @typecad/framework-native). The Zephyr
+// counterpart is framework-zephyr/src/debug-codegen.ts (printk + a shim-side
+// halt). Dispatched by cuttlefish/src/debug/preprocessor.ts.
+// ---------------------------------------------------------------------------
+import { escapeCppStringLiteral } from "../utils/strings.js";
+/**
+ * Wrap a C++ text fragment as an injectable TS statement. The rawCpp() call
+ * lowers to __EMIT__, whose string argument the emitter writes out verbatim
+ * (a trailing `;` is added by the emitter when the fragment lacks one).
+ * JSON.stringify produces a valid single-line TS double-quoted literal for
+ * any fragment, newlines included.
+ */
+function raw(cpp) {
+    return `rawCpp(${JSON.stringify(cpp)});`;
+}
+/** printf a string literal. */
+function printLiteral(text, indent) {
+    return raw(`${indent}printf("%s", "${escapeCppStringLiteral(text)}");`);
+}
+/**
+ * Generate the debug-mode banner. The host console needs no setup, but the
+ * printf/getchar calls below need <cstdio>: include() registers it on the
+ * program (the generic strategy's forcedIncludes is deliberately empty), and
+ * the strategy-side usesCstdio gates (e.g. native) also pick the banner up
+ * from the rawCpp text.
+ */
+export function generateGenericInitCode() {
+    return [
+        '// === DEBUG: host console (printf) ===',
+        "include('<cstdio>');",
+        raw('printf("[TypeCAD] Debug Mode Active\\n");'),
+        '// === END DEBUG INIT ===',
+        '',
+    ];
+}
+/**
+ * Generate generic/native code for a breakpoint.
+ *
+ * The halt reads stdin until ENTER; any 's' typed before it marks this
+ * breakpoint skipped for the rest of the run. The flag is a C++ static local
+ * inside the emitted block (safe here — unlike TS-injected declarations, the
+ * rawCpp text bypasses the TS parser entirely), so the skip persists across
+ * loop() iterations. EOF on stdin exits the halt instead of spinning.
+ *
+ * When `breakpointId` is set the whole block is guarded by that flag; the
+ * preprocessor assigns ids to every halting breakpoint.
+ */
+export function generateGenericBreakpointCode(fileName, lineNum, originalLine, variables, normalizedCondition, breakpointId) {
+    const lines = [];
+    const indent = '  ' + (normalizedCondition ? '  ' : '');
+    lines.push(`  // === BREAKPOINT: ${fileName}:${lineNum} ===`);
+    if (normalizedCondition) {
+        lines.push(`  if (${normalizedCondition}) {`);
+    }
+    // The whole breakpoint is one rawCpp block: a braced C++ compound
+    // statement. The emitter only appends a `;` when the fragment lacks one,
+    // so a block ending in `}` is written out verbatim.
+    const flag = breakpointId !== undefined ? `__tc_bp${breakpointId}_skipped` : undefined;
+    const b = ['{'];
+    const inner = flag ? '  ' : '';
+    if (flag) {
+        b.push(`  static bool ${flag} = false;`);
+        b.push(`  if (!${flag}) {`);
+    }
+    b.push(`${inner}printf("----------------------------------------\\n");`);
+    const headerText = normalizedCondition
+        ? `[BREAK] ${fileName}:${lineNum} (condition: ${escapeCppStringLiteral(normalizedCondition)})`
+        : `[BREAK] ${fileName}:${lineNum}`;
+    b.push(`${inner}printf("%s\\n", "${escapeCppStringLiteral(headerText)}");`);
+    b.push(`${inner}printf("  %s\\n", "${escapeCppStringLiteral(originalLine)}");`);
+    if (variables.length > 0) {
+        b.push(`${inner}printf("  Variables:\\n");`);
+        for (const v of variables) {
+            if (v.isFunction) {
+                b.push(`${inner}printf("  - %s = [function]\\n", "${escapeCppStringLiteral(v.name)}");`);
+            }
+            else {
+                const { spec, arg } = formatSpecFor(v.name, v.cppType);
+                b.push(`${inner}printf("  - %s = ${spec}\\n", "${escapeCppStringLiteral(v.name)}", ${arg});`);
+            }
+        }
+    }
+    else {
+        b.push(`${inner}printf("  (no variables in scope)\\n");`);
+    }
+    b.push(`${inner}printf("  [ENTER: continue | s: skip this breakpoint]\\n");`);
+    b.push(`${inner}int __tc_c;`);
+    if (flag) {
+        b.push(`${inner}do {`);
+        b.push(`${inner}  __tc_c = getchar();`);
+        b.push(`${inner}  if (__tc_c == 's') { ${flag} = true; }`);
+        b.push(`${inner}} while (__tc_c != '\\n' && __tc_c != EOF);`);
+    }
+    else {
+        b.push(`${inner}do {`);
+        b.push(`${inner}  __tc_c = getchar();`);
+        b.push(`${inner}} while (__tc_c != '\\n' && __tc_c != EOF);`);
+    }
+    if (flag) {
+        b.push('  }');
+    }
+    b.push('}');
+    lines.push(indent + raw(b.join('\n')));
+    if (normalizedCondition) {
+        lines.push(`  }`);
+    }
+    lines.push(`  // === END BREAKPOINT ===`);
+    return lines;
+}
+/**
+ * Generate generic/native code for a logpoint (logs a message without
+ * halting). Each part is its own printf, then a newline.
+ */
+export function generateGenericLogpointCode(fileName, lineNum, parts, variables) {
+    const lines = [];
+    lines.push(`  // === LOGPOINT: ${fileName}:${lineNum} ===`);
+    lines.push(raw(`  printf("%s", "${escapeCppStringLiteral(`[LOG ${fileName}:${lineNum}] `)}");`));
+    for (const part of parts) {
+        if (part.type === 'text') {
+            lines.push(raw(`  printf("%s", "${escapeCppStringLiteral(part.value)}");`));
+        }
+        else {
+            // Variable part: only printable if it is a non-function value in scope.
+            const match = variables.find((v) => v.name === part.value && !v.isFunction);
+            if (match) {
+                const { spec, arg } = formatSpecFor(match.name, match.cppType);
+                lines.push(raw(`  printf("${spec}", ${arg});`));
+            }
+            else {
+                lines.push(raw(`  printf("%s", "{${escapeCppStringLiteral(part.value)}}"); // variable not in scope`));
+            }
+        }
+    }
+    lines.push(raw(`  printf("\\n");`));
+    lines.push(`  // === END LOGPOINT ===`);
+    return lines;
+}
+/**
+ * Pick a printf format specifier + argument expression for a debug variable.
+ *
+ * The debug preprocessor has no TypeChecker, so `cppType` is a coarse
+ * category inferred from AST shape. Native/generic mappings:
+ *   - bool        → %d via static_cast<int>
+ *   - int/long    → %lld via static_cast<long long> (native `number` is long
+ *                   long; int32_t widens into the same cast)
+ *   - float       → %g via static_cast<double> (float literal widens)
+ *   - string      → %s via .c_str() (native strings are std::string)
+ *   - unknown     → %g via static_cast<double>, the documented fallback that
+ *                   compiles for any numeric/bool variable.
+ */
+function formatSpecFor(varName, cppType) {
+    switch (cppType) {
+        case 'bool':
+            return { spec: '%d', arg: `static_cast<int>(${varName})` };
+        case 'int':
+        case 'long':
+            return { spec: '%lld', arg: `static_cast<long long>(${varName})` };
+        case 'float':
+            return { spec: '%g', arg: `static_cast<double>(${varName})` };
+        case 'string':
+            return { spec: '%s', arg: `${varName}.c_str()` };
+        case 'unknown':
+        default:
+            // Cast to double so printf compiles regardless of the real C++ type.
+            return { spec: '%g', arg: `static_cast<double>(${varName})` };
+    }
+}

package/dist/platform/generic-strategy.d.ts

@@ -34,9 +34,6 @@ export declare class GenericStrategy implements PlatformStrategy {
     enumCastType(enumName: string): string | undefined;
     renderBoardDefinitionAccess(_chain: string[], _boardConstants?: BoardConstants): string | undefined;
     renderThrow(valueExpr: string): string;
-    isConsoleCall(callee: string): boolean;
-    transformConsoleCall(method: string, renderedArgs: string, forHeader: boolean): string;
-    transformConsoleExpression(method: string, _renderedArgs: string): string | undefined;
     objectFieldInitializer(_fieldValue: ExpressionIR, _renderExpr: (e: ExpressionIR) => string): string | undefined;
     overrideClassFieldType(_fieldName: string, _normalizedType: string): string;
     reservedNames(): ReadonlySet<string>;
@@ -50,7 +47,6 @@ export declare class GenericStrategy implements PlatformStrategy {
     needsStdFunction(): boolean;
     mathHeader(): string;
     cstringHeader(): string;
-    needsVectorOverload(): boolean;
     needsLargeEnumUnderlying(): boolean;
     renameStructField(fieldName: string): string;
     structFieldInitializer(_fieldValue: ExpressionIR, _compiletimeVarNames: Set<string>, _renderExpr: (e: ExpressionIR) => string): string | undefined;
@@ -79,8 +75,10 @@ export declare class GenericStrategy implements PlatformStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
         }>;
         normalizedCondition?: string;
+        breakpointId?: number;
     }): string[];
     generateDebugLogpointCode(params: {
         fileName: string;
@@ -92,6 +90,7 @@ export declare class GenericStrategy implements PlatformStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
         }>;
     }): string[];
     resolveDisplayOp(_op: DisplayHALOp): {

package/dist/platform/generic-strategy.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
-// GenericStrategy — standard C++ target (std::cout, main(), <cmath> …)
+// GenericStrategy — standard C++ target (main(), <cmath> …)
 // ---------------------------------------------------------------------------
-import { escapeCppStringLiteral } from "../utils/strings.js";
+import { generateGenericInitCode, generateGenericBreakpointCode, generateGenericLogpointCode } from "./generic-debug-codegen.js";
 import { DEFAULT_STDLIB_SUPPORT } from "../api/shared/index.js";
 import { parsedIsPointer } from "../api/shared/cpp-type-ir.js";
 import { buildAsyncRuntimePolyfill } from "./async-runtime.js";
@@ -105,37 +105,6 @@ export class GenericStrategy {
     renderThrow(valueExpr) {
         return `throw ${valueExpr};`;
     }
-    isConsoleCall(callee) {
-        return callee.startsWith("console.");
-    }
-    transformConsoleCall(method, renderedArgs, forHeader) {
-        const semi = forHeader ? "" : ";";
-        switch (method) {
-            case "log":
-            case "info":
-            case "debug":
-                return `std::cout << ${renderedArgs} << std::endl${semi}`;
-            case "error":
-                return `std::cerr << "[ERROR] " << ${renderedArgs} << std::endl${semi}`;
-            case "warn":
-                return `std::cerr << "[WARN] " << ${renderedArgs} << std::endl${semi}`;
-            case "readLine":
-            case "readCharacter":
-                return this.transformConsoleExpression(method, renderedArgs) + semi;
-            default:
-                return `std::cout << ${renderedArgs} << std::endl${semi}`;
-        }
-    }
-    transformConsoleExpression(method, _renderedArgs) {
-        switch (method) {
-            case 'readLine':
-                return '([]() -> std::string { std::string s; std::getline(std::cin, s); return s; })()';
-            case 'readCharacter':
-                return '([&]() -> char { std::cout << "> " << std::flush; return std::cin.get(); })()';
-            default:
-                return undefined;
-        }
-    }
     objectFieldInitializer(_fieldValue, _renderExpr) {
         return undefined;
     }
@@ -163,7 +132,6 @@ export class GenericStrategy {
     needsStdFunction() { return true; }
     mathHeader() { return "<cmath>"; }
     cstringHeader() { return "<cstring>"; }
-    needsVectorOverload() { return true; }
     // ── Enum underlying type ────────────────────────────────────────────────
     needsLargeEnumUnderlying() { return false; }
     // ── Struct field handling ───────────────────────────────────────────────
@@ -227,56 +195,13 @@ export class GenericStrategy {
         return 'printf';
     }
     generateDebugInitCode() {
-        return [
-            '// === DEBUG: Initialize ===',
-            'std::cout << "TypeCAD Debug Mode Active" << std::endl;',
-            '// === END DEBUG INIT ===',
-            '',
-        ];
+        return generateGenericInitCode();
     }
     generateDebugBreakpointCode(params) {
-        const lines = [];
-        lines.push(`  // === BREAKPOINT: ${params.fileName}:${params.lineNum} ===`);
-        if (params.normalizedCondition) {
-            lines.push(`  if (${params.normalizedCondition}) {`);
-        }
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "━━━━━━━━━━━━━━━━━━━━━━━━━━━━" << std::endl;`);
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "BREAKPOINT: ${params.fileName}:${params.lineNum}" << std::endl;`);
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${params.originalLine.replace(/"/g, '\\"')}" << std::endl;`);
-        if (params.variables.length > 0) {
-            lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  Variables:" << std::endl;`);
-            for (const v of params.variables) {
-                if (v.isFunction) {
-                    lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${v.name} = [function]" << std::endl;`);
-                }
-                else {
-                    lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${v.name} = " << ${v.name} << std::endl;`);
-                }
-            }
-        }
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "━━━━━━━━━━━━━━━━━━━━━━━━━━━━" << std::endl;`);
-        if (params.normalizedCondition) {
-            lines.push(`  }`);
-        }
-        lines.push(`  // === END BREAKPOINT ===`);
-        return lines;
+        return generateGenericBreakpointCode(params.fileName, params.lineNum, params.originalLine, params.variables, params.normalizedCondition, params.breakpointId);
     }
     generateDebugLogpointCode(params) {
-        const lines = [];
-        lines.push(`  // === LOGPOINT: ${params.fileName}:${params.lineNum} ===`);
-        const parts = [`"[LOG ${params.fileName}:${params.lineNum}] "`];
-        for (const part of params.parts) {
-            if (part.type === 'text') {
-                parts.push(`"${escapeCppStringLiteral(part.value)}"`);
-            }
-            else {
-                const varExists = params.variables.some(v => v.name === part.value && !v.isFunction);
-                parts.push(varExists ? part.value : `"${escapeCppStringLiteral(part.value)}"`);
-            }
-        }
-        lines.push(`  std::cout << ${parts.join(' << ')} << std::endl;`);
-        lines.push(`  // === END LOGPOINT ===`);
-        return lines;
+        return generateGenericLogpointCode(params.fileName, params.lineNum, params.parts, params.variables);
     }
     // ── Graphics (fallback) ────────────────────────────────────────────────
     resolveDisplayOp(_op) {

package/dist/platform/index.js

@@ -2,7 +2,7 @@
 // Platform strategy exports
 //
 // Re-exports platform strategies for use within the CLI and by consumers.
-// Framework-specific strategies (e.g. ArduinoStrategy) are provided by their
+// Framework-specific strategies (e.g. ZephyrStrategy) are provided by their
 // respective framework packages, which register via registerPlatformStrategy().
 // ---------------------------------------------------------------------------
 export { GenericStrategy } from './generic-strategy.js';

package/dist/platform/registry.d.ts

@@ -4,9 +4,9 @@ import type { PlatformStrategy } from "../api/shared/index.js";
  * their entry point to override the default strategy for a target.
  *
  * @example
- * // In @typecad/framework-arduino
+ * // In @typecad/framework-zephyr
  * import { registerPlatformStrategy } from "@typecad/cuttlefish/platform/registry";
- * registerPlatformStrategy(new ArduinoStrategy());
+ * registerPlatformStrategy(new ZephyrStrategy());
  */
 export declare function registerPlatformStrategy(strategy: PlatformStrategy): void;
 /**

package/dist/platform/registry.js

@@ -15,9 +15,9 @@ const _registry = new Map([
  * their entry point to override the default strategy for a target.
  *
  * @example
- * // In @typecad/framework-arduino
+ * // In @typecad/framework-zephyr
  * import { registerPlatformStrategy } from "@typecad/cuttlefish/platform/registry";
- * registerPlatformStrategy(new ArduinoStrategy());
+ * registerPlatformStrategy(new ZephyrStrategy());
  */
 export function registerPlatformStrategy(strategy) {
     _registry.set(strategy.id, strategy);

package/dist/safety/asil-decorators.d.ts

@@ -0,0 +1,32 @@
+export {};
+/** ASIL level annotations for functions — comment-based.
+ *
+ *  ASIL levels are declared via leading comment annotations rather than
+ *  TypeScript decorators because:
+ *  - TS decorators on function declarations produce TS1206 errors in the
+ *    VS Code language server and @typescript-eslint/parser
+ *  - Comment annotations work in any editor, any toolchain, without
+ *    `experimentalDecorators` or special config
+ *
+ *  The cuttlefish IR builder extracts these from leading comments via
+ *  extractAsilFromComments() in function-builder.ts.
+ *
+ *  Part B's ISO 26262 checkers (analyzeIR) read the resulting `decorators`
+ *  field on FunctionIR to decide which rules to enforce:
+ *
+ *    // @asilD → all rules enforced (recursion, heap, loops)
+ *    // @asilC → recursion + loops enforced (heap is ASIL D only)
+ *    // @asilB → recursion enforced
+ *    // @asilA → no rules enforced (quality-managed)
+ *    (no annotation) → no rules enforced (implicit QM)
+ *
+ *  Usage:
+ *    // @asilD
+ *    function engageBrake(): void {
+ *      safe.write(brakePin, 1);
+ *    }
+ *
+ *  These are documentation-only exports — they have no runtime behavior
+ *  and are never imported by user code. They exist so the ASIL level
+ *  names appear in type hints and IDE autocomplete.
+ */

package/dist/safety/asil-decorators.js

@@ -0,0 +1,32 @@
+export {};
+/** ASIL level annotations for functions — comment-based.
+ *
+ *  ASIL levels are declared via leading comment annotations rather than
+ *  TypeScript decorators because:
+ *  - TS decorators on function declarations produce TS1206 errors in the
+ *    VS Code language server and @typescript-eslint/parser
+ *  - Comment annotations work in any editor, any toolchain, without
+ *    `experimentalDecorators` or special config
+ *
+ *  The cuttlefish IR builder extracts these from leading comments via
+ *  extractAsilFromComments() in function-builder.ts.
+ *
+ *  Part B's ISO 26262 checkers (analyzeIR) read the resulting `decorators`
+ *  field on FunctionIR to decide which rules to enforce:
+ *
+ *    // @asilD → all rules enforced (recursion, heap, loops)
+ *    // @asilC → recursion + loops enforced (heap is ASIL D only)
+ *    // @asilB → recursion enforced
+ *    // @asilA → no rules enforced (quality-managed)
+ *    (no annotation) → no rules enforced (implicit QM)
+ *
+ *  Usage:
+ *    // @asilD
+ *    function engageBrake(): void {
+ *      safe.write(brakePin, 1);
+ *    }
+ *
+ *  These are documentation-only exports — they have no runtime behavior
+ *  and are never imported by user code. They exist so the ASIL level
+ *  names appear in type hints and IDE autocomplete.
+ */

package/dist/safety/authoring.d.ts

@@ -0,0 +1,85 @@
+export type { SafeVariable } from "./safe-variable-types.js";
+export type { SafeInt } from "./safe-int-types.js";
+import type { Pin } from "@typecad/hal";
+/** The pin argument safe.read accepts — a thin-HAL `GPIO`. A named alias so
+ *  the safety API's stringified type stays free of union syntax at call sites.
+ *  At runtime the safety package resolves the same `_pin: number` field via
+ *  the halInstances registry at IR time. */
+export type AnyPin = Pin;
+/** Two-tier fault taxonomy. Stable across safety standards (ISO 26262,
+ *  IEC 61508, DO-178C). The category is the coarse user-space routing axis;
+ *  the code is standard-specific detail.
+ *
+ *  Declared as TypeScript `enum` (not `const` object + type alias) so the
+ *  cuttlefish transpiler lowers these to a single C++ `enum class` definition
+ *  matching the runtime polyfill's enum, rather than emitting a conflicting
+ *  struct per usage scope. The transpiler's enum lowering and the polyfill's
+ *  enum class are structurally identical (same tag name, same enumerators,
+ *  same values). */
+export declare enum SafetyFaultCategory {
+    Ok = 1010580540,
+    Signal = 1515870810,
+    Integrity = 2779096485,
+    Timing = 3284386755,
+    System = 1437226410,
+    Configuration = 2857740885
+}
+export declare enum SafetyFaultCode {
+    Ok = 1010580540,
+    VoteDisagreement = 1515870810,
+    StuckHigh = 2779096485,
+    StuckLow = 3284386755,
+    PinModeMismatch = 1437226410,
+    PinModeUnknown = 2857740885,
+    WriteMismatch = 1012573635
+}
+export declare enum SafetyStatus {
+    Ok = 1515870810,
+    Fault = 2779096485
+}
+export interface SafeReadResult {
+    readonly status: SafetyStatus;
+    readonly value: number;
+    readonly category: SafetyFaultCategory;
+    readonly code: SafetyFaultCode;
+    /** Run handler iff status === Ok. Handler receives the full result. Returns the result (chainable). */
+    ok(handler: (r: SafeReadResult) => void): SafeReadResult;
+    /** Run handler iff status !== Ok. Handler receives the full result. Returns the result (chainable). */
+    fail(handler: (r: SafeReadResult) => void): SafeReadResult;
+    /** Alias of fail(). */
+    fault(handler: (r: SafeReadResult) => void): SafeReadResult;
+    /** Run handler unconditionally. Returns the result (chainable). */
+    always(handler: (r: SafeReadResult) => void): SafeReadResult;
+}
+export interface SafeWriteResult {
+    readonly status: SafetyStatus;
+    readonly code: SafetyFaultCode;
+    ok(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+    fail(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+    fault(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+    always(handler: (r: SafeWriteResult) => void): SafeWriteResult;
+}
+/** Safe GPIO API. Compile-time construct only — the cuttlefish transpiler
+ *  intercepts safe.read and lowers it to a safety.read_safe HAL op. The
+ *  type annotation (rather than `as const`) gives `safe` a single object
+ *  type so member access doesn't lower to std::variant access — same reason
+ *  @typecad/ui's `ui` uses an explicit type annotation. */
+export declare const safe: {
+    /** Safe digital read: confirms the pin's recorded mode is INPUT or
+     *  INPUT_PULLUP (via the auto-populated mode table), performs a 2-of-3
+     *  vote via the strategy-injected __tc_gpio_read shim, returns a
+     *  SafeReadResult carrying any detected fault.
+     *
+     *  Accepts any thin-HAL GPIO regardless of its constructed flag set. The
+     *  runtime mode-table check (driven by the GPIO's construction flags)
+     *  rejects pins configured as OUTPUT (returns PinModeMismatch). */
+    read(pin: AnyPin): SafeReadResult;
+    /** Safe digital write with readback verification. Writes the value,
+     *  immediately reads the physical pin state back, and returns a
+     *  SafeWriteResult confirming the write succeeded or flagging a fault.
+     *
+     *  Verifies the pin's recorded mode is OUTPUT (returns PinModeMismatch
+     *  for non-output pins). On write/read mismatch, returns
+     *  WriteMismatch. */
+    write(pin: Pin, value: number): SafeWriteResult;
+};