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

package/dist/api/shared/native-display-op-resolver.js

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Shared display-op resolver for native (non-Arduino) display strategies.
+//
+// Both NativeAVRStrategy and Esp32Strategy override resolveDisplayOp to return
+// undefined for display.* ops (the design intent: display ops are resolved
+// through the adapter path, not per-op HAL lowering). But the HAL lowering
+// layer still calls resolveDisplayOp for every display.* op emitted by user
+// code (display.init via ui.mount, display.fill_rect/draw_rect/draw_text via
+// direct HAL calls, display.flush per frame).
+//
+// Those ops need to lower to CALLS INTO the adapter surface — the same
+// display_init() / display_targetFillRect() / etc. functions the Adafruit
+// path calls. The native adapters emit those functions with identical
+// signatures, so the lowering is identical across native strategies.
+//
+// This module provides that lowering. Each native strategy's resolveDisplayOp
+// delegates here instead of returning undefined.
+// ---------------------------------------------------------------------------
+/** Render a color value as a C++ hex literal (e.g. 0x07e0) for readable RGB565. */
+function hexColor(c) {
+    return `0x${c.toString(16)}`;
+}
+/**
+ * Resolve a display HAL op to a call into the native adapter surface
+ * (display_init / display_targetFillRect / etc.). Returns undefined for ops
+ * this resolver does not handle.
+ */
+export function resolveNativeDisplayOp(op) {
+    switch (op.operation) {
+        case "display.init":
+            // The adapter's display_init() does bus setup, panel init sequence,
+            // rotation, and the initial fillScreen. No backlight GPIO parameter
+            // on native paths — the Adafruit-style backlight pin is handled in
+            // the mount config if needed.
+            return { code: `display_init();` };
+        case "display.fill_rect":
+            // Delegate to the polymorphic target draw so the same call works
+            // whether the active target is the panel or an offscreen canvas.
+            return {
+                code: `display_targetFillRect(display_defaultTarget(), ${op.x}, ${op.y}, ${op.w}, ${op.h}, ${hexColor(op.color)});`,
+            };
+        case "display.draw_rect":
+            return {
+                code: `display_targetDrawRect(display_defaultTarget(), ${op.x}, ${op.y}, ${op.w}, ${op.h}, ${hexColor(op.color)});`,
+            };
+        case "display.draw_text":
+            return {
+                code: [
+                    `display_targetSetCursor(display_defaultTarget(), ${op.x}, ${op.y});`,
+                    `display_targetSetTextColor(display_defaultTarget(), ${hexColor(op.color)});`,
+                    `display_targetSetTextSize(display_defaultTarget(), 2);`,
+                    `display_targetPrint(display_defaultTarget(), ${JSON.stringify(op.text)});`,
+                ].join("\n"),
+            };
+        case "display.flush":
+            // Direct-mode panels (ILI9341, ST7796S) draw immediately — no flush.
+            // Buffered panels (SSD1309) flush via display_partial_refresh, which
+            // the runtime calls through display_partial_refresh directly (not via
+            // HAL op) at frame end.
+            return { code: `/* flush: ${op.rects.length} rect(s) — native display */` };
+        default:
+            return undefined;
+    }
+}

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

@@ -279,6 +279,15 @@ export interface PlatformSafetyStrategy {
      * StaticArray wrapper's methods or the std::vector/__tc_* helper form.
      */
     promotesArrayLiteralsToStaticArray?(): boolean;
+    /**
+     * Whether this target runs on a preemptive RTOS where blocking calls
+     * (e.g. vTaskDelay) yield the CPU to other tasks. When true, delay() inside
+     * loop() does NOT freeze the async queue or UI rendering — the timing
+     * validator suppresses the 'blocking-delay-in-loop' warning for plain delay().
+     * Defaults to false (Arduino/AVR use cooperative scheduling where delay
+     * freezes everything). ESP-IDF (FreeRTOS) returns true.
+     */
+    isRtosTarget?(): boolean;
 }
 export interface PlatformBuildStrategy {
     /** Queue capacity for the async microtask ring buffer. */

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

@@ -181,6 +181,84 @@ namespace typecad_async {
     std::vector<std::function<void(const std::string&)>> _onRejected;
   };
 
+  // Promise<void> — T=_value/const T& is illegal for void. Helpers below pass
+  // resolve as std::function<void(const void*)> (pointer, not reference).
+  template <>
+  class Promise<void> {
+  public:
+    enum class State { Pending, Fulfilled, Rejected };
+
+    using ResolveFn = std::function<void(const void*)>;
+    using RejectFn = std::function<void(const std::string&)>;
+    using Executor = std::function<void(ResolveFn, RejectFn)>;
+
+    Promise() : _state(State::Pending), _error{} {}
+
+    explicit Promise(Executor executor)
+      : _state(State::Pending), _error{} {
+      executor(
+        [this](const void*) { this->resolve(nullptr); },
+        [this](const std::string& error) { this->reject(error); }
+      );
+    }
+
+    static Promise<void> resolveValue() {
+      Promise<void> promise;
+      promise.resolve(nullptr);
+      return promise;
+    }
+
+    static Promise<void> rejectValue(const std::string& error) {
+      Promise<void> promise;
+      promise.reject(error);
+      return promise;
+    }
+
+    void resolve(const void* = nullptr) {
+      if (_state != State::Pending) return;
+      _state = State::Fulfilled;
+      auto callbacks = _onFulfilled;
+      enqueueMicrotask([callbacks]() mutable {
+        for (auto& callback : callbacks) { callback(nullptr); }
+      });
+    }
+
+    void reject(const std::string& error) {
+      if (_state != State::Pending) return;
+      _state = State::Rejected;
+      _error = error;
+      auto callbacks = _onRejected;
+      enqueueMicrotask([callbacks, error]() mutable {
+        for (auto& callback : callbacks) { callback(error); }
+      });
+    }
+
+    Promise<void>& then(std::function<void(const void*)> onFulfilled) {
+      if (_state == State::Fulfilled) {
+        enqueueMicrotask([onFulfilled]() mutable { onFulfilled(nullptr); });
+      } else if (_state == State::Pending) {
+        _onFulfilled.push_back(std::move(onFulfilled));
+      }
+      return *this;
+    }
+
+    Promise<void>& catchError(std::function<void(const std::string&)> onRejected) {
+      if (_state == State::Rejected) {
+        const std::string error = _error;
+        enqueueMicrotask([onRejected, error]() mutable { onRejected(error); });
+      } else if (_state == State::Pending) {
+        _onRejected.push_back(std::move(onRejected));
+      }
+      return *this;
+    }
+
+  private:
+    State _state;
+    std::string _error;
+    std::vector<std::function<void(const void*)>> _onFulfilled;
+    std::vector<std::function<void(const std::string&)>> _onRejected;
+  };
+
   // ── HAL-level implementations (inside namespace so they see Promise<T> and enqueueMicrotask) ──
 
   // Async.sleep() — cooperative delay using millis polling

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

@@ -26,6 +26,14 @@ export interface Diagnostic {
     column?: number;
     code?: string;
     source?: string;
+    /**
+     * Path (or basename) of the source file the diagnostic refers to. When set,
+     * it is rendered in the diagnostic header so the location is not just
+     * `(line,col)` but `path/to/file.ts (line,col)`. Emitters should prefer the
+     * real file path from the originating node's sourceSpan, falling back to a
+     * basename when the full path is unavailable.
+     */
+    filePath?: string;
     /** Text of the source line for display context. */
     sourceLine?: string;
 }

package/dist/api/shared/validate-framework-manifest.d.ts

@@ -0,0 +1,28 @@
+import type { PlatformStrategy } from './platform-strategy.js';
+import type { FrameworkToolchain } from '../../framework-registry.js';
+import type { FrameworkManifest } from './framework-manifest.js';
+export interface ManifestValidationContext {
+    strategy: PlatformStrategy;
+    toolchain?: FrameworkToolchain;
+    moduleExports: Record<string, unknown>;
+    packageRoot: string;
+    repoTestsDir: string;
+}
+export interface ManifestValidationError {
+    code: string;
+    path: string;
+    message: string;
+    subject?: string;
+}
+export interface ManifestValidationWarning {
+    code: string;
+    path: string;
+    message: string;
+    subject?: string;
+}
+export interface ManifestValidationResult {
+    valid: boolean;
+    errors: ManifestValidationError[];
+    warnings: ManifestValidationWarning[];
+}
+export declare function validateFrameworkManifest(manifest: FrameworkManifest, ctx: ManifestValidationContext): ManifestValidationResult;

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

@@ -0,0 +1,417 @@
+// ---------------------------------------------------------------------------
+// Framework manifest validator
+//
+// Cross-checks each manifest claim against the loaded PlatformStrategy,
+// Toolchain, and module exports. Errors are plain data (not thrown) so the
+// validator can be called from tests, a future CLI, or agents reading errors
+// programmatically.
+//
+// Categories A-H are documented in docs/framework-manifest-error-codes.md.
+// ---------------------------------------------------------------------------
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { POLYFILL_BACKED_OPS } from './framework-manifest.js';
+import { HAL_OPERATION_KINDS } from './hal-op-ir.js';
+import { DISPLAY_OPERATION_KINDS } from './display-op-ir.js';
+class Accumulator {
+    constructor() {
+        this.errors = [];
+        this.warnings = [];
+    }
+    error(code, path, message, subject) {
+        this.errors.push({ code, path, message, subject });
+    }
+    warning(code, path, message, subject) {
+        this.warnings.push({ code, path, message, subject });
+    }
+}
+// Map each HAL category to the prefix its op kinds share.
+const CATEGORY_PREFIXES = {
+    gpio: ['gpio.'],
+    pwm: ['pwm.'],
+    adc: ['adc.'],
+    dac: ['dac.'],
+    interrupts: ['interrupt.'],
+    tone: ['tone.'],
+    timing: ['timing.'],
+    power: ['power.'],
+    i2c: ['i2c.'],
+    spi: ['spi.'],
+    uart: ['uart.'],
+    pulse: ['pulse.'],
+    shift: ['shift.'],
+    board: ['board.'],
+    wdt: ['wdt.'],
+    wifi: ['wifi.'],
+    http: ['http.'],
+    display: ['display.'],
+    preferences: ['preferences.'],
+};
+function opKindsForCategory(category) {
+    const prefixes = CATEGORY_PREFIXES[category] ?? [];
+    const all = [...HAL_OPERATION_KINDS, ...DISPLAY_OPERATION_KINDS];
+    return all.filter((k) => prefixes.some((p) => k.startsWith(p)));
+}
+// Minimal valid payloads for op kinds whose resolver requires more than just
+// the operation discriminator. The default probe (just `{ operation: kind }`)
+// works for most ops; this map fills in the smallest payload that lets the
+// resolver run without throwing on missing-arg validation.
+//
+// Templates must be the MINIMAL payload the resolver needs — enough to prove
+// the framework handles the op, not to produce semantically correct output.
+// Keep entries scoped to fields the resolver actually destructures.
+const OP_PROBE_PAYLOADS = {
+    // i2c.write_bytes requires bus + bytes (resolver iterates bytes).
+    'i2c.write_bytes': { bus: 'i2c0', address: 0x50, bytes: [0x00, 0x01] },
+    // uart.printf requires format + args (resolver joins args).
+    'uart.printf': { port: 'Serial', format: '%d', args: ['x'] },
+    // adc.read / adc.read_voltage require pin.
+    'adc.read': { pin: 0 },
+    'adc.read_voltage': { pin: 0 },
+    // dac.write requires pin + value. Use pin 25 (a valid DAC pin on ESP32;
+    // pin 0 throws "not a DAC pin" on ESP32 and Arduino maps it to a
+    // non-DAC pin too).
+    'dac.write': { pin: 25, value: 128 },
+    // display.* require coordinates/color (still inconclusive without driver
+    // context — included so future driver-aware probes can build on them).
+    'display.fill_rect': { x: 0, y: 0, w: 10, h: 10, color: 0xffff },
+    'display.draw_text': { x: 0, y: 0, text: 'x', font: '8x16', color: 0xffff },
+    'display.draw_rect': { x: 0, y: 0, w: 10, h: 10, color: 0xffff },
+    'display.flush': { rects: [{ x: 0, y: 0, w: 10, h: 10 }] },
+};
+// Builds a HALOpIR probe. Uses OP_PROBE_PAYLOADS when available so resolvers
+// that destructure required fields don't throw on the probe itself.
+function buildHalProbe(opKind) {
+    const payload = OP_PROBE_PAYLOADS[opKind];
+    return { operation: opKind, ...(payload ?? {}) };
+}
+function buildDisplayProbe(opKind) {
+    const payload = OP_PROBE_PAYLOADS[opKind];
+    return { operation: opKind, ...(payload ?? {}) };
+}
+function probeResolve(strategy, opKind) {
+    const isDisplay = opKind.startsWith('display.');
+    try {
+        const op = isDisplay ? buildDisplayProbe(opKind) : buildHalProbe(opKind);
+        const result = isDisplay
+            ? strategy.resolveDisplayOp?.(op)
+            : strategy.resolveHALOperation?.(op);
+        if (!result)
+            return 'undefined';
+        if (result.code !== undefined)
+            return 'code';
+        if (result.expression !== undefined)
+            return 'expression';
+        return 'undefined';
+    }
+    catch {
+        return 'thrown';
+    }
+}
+function statusFromResolution(res) {
+    return res === 'undefined' || res === 'thrown' ? 'no-emit' : 'lowers';
+}
+// ---------------------------------------------------------------------------
+// Category A — identity
+// ---------------------------------------------------------------------------
+function validateIdentity(manifest, ctx, acc) {
+    const strategyId = ctx.strategy.id;
+    const matchesDirect = strategyId === manifest.frameworkId;
+    const matchesInherited = manifest.inheritsStrategyId !== undefined &&
+        manifest.inheritsStrategyId === strategyId;
+    if (!matchesDirect && !matchesInherited) {
+        acc.error('identity/id-mismatch', 'frameworkId', `manifest.frameworkId is "${manifest.frameworkId}" but strategy.id is "${strategyId}". ` +
+            `Set strategy.id to match, or add "inheritsStrategyId: "${strategyId}"" to the manifest ` +
+            `to document intentional id reuse.`, manifest.frameworkId);
+    }
+}
+// ---------------------------------------------------------------------------
+// Category B — entrypoint
+// ---------------------------------------------------------------------------
+function validateEntrypoint(manifest, ctx, acc) {
+    const ep = manifest.entrypoint;
+    const strat = ctx.strategy;
+    const checks = [
+        ['entrypointFunctionName', ep.entrypointFunctionName, strat.entrypointFunctionName()],
+        ['requiresLoopFunction', ep.requiresLoopFunction, strat.requiresLoopFunction()],
+        ['sourceExtension', ep.sourceExtension, strat.sourceExtension(true, false)],
+        ['generateHeaderFile', ep.generateHeaderFile, strat.generateHeaderFile()],
+    ];
+    for (const [field, declared, actual] of checks) {
+        if (declared !== actual) {
+            acc.error(`entrypoint/${field}/mismatch`, `entrypoint.${field}`, `manifest declares ${field}=${JSON.stringify(declared)} but strategy returns ${JSON.stringify(actual)}.`, field);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Category C — HAL coverage
+// ---------------------------------------------------------------------------
+function validateHalCoverage(manifest, ctx, acc) {
+    for (const [category, declarationRaw] of Object.entries(manifest.hal)) {
+        if (category === 'raw')
+            continue;
+        const declaration = declarationRaw;
+        const knownKinds = opKindsForCategory(category);
+        // Check that every known op kind for this category appears in ops.
+        for (const kind of knownKinds) {
+            if (!(kind in declaration.ops)) {
+                acc.error(`hal/${category}/op/${kind}/undeclared`, `hal.${category}.ops.${kind}`, `manifest.hal.${category}.ops is missing "${kind}". Add it with a status of supported/stub/unsupported.`, kind);
+            }
+        }
+        // Probe each declared op and cross-check status vs resolver behavior.
+        for (const [kind, status] of Object.entries(declaration.ops)) {
+            // 'probe-inconclusive' is an explicit acknowledgment that the minimal
+            // probe (just an operation discriminator) cannot determine support —
+            // typically because the resolver needs a valid pin/config payload.
+            // The validator does not cross-check these; the renderer flags them
+            // for manual review. This keeps the matrix honest without penalizing
+            // frameworks for the probe's limitations.
+            if (status === 'probe-inconclusive')
+                continue;
+            // 'polyfill' means the op is backed by a runtime polyfill, NOT by
+            // resolveHALOperation. Verify the named polyfill exists in
+            // POLYFILL_BACKED_OPS and is declared in polyfills.emitted.
+            // No HAL probe — the resolver legitimately returns undefined for these.
+            if (status === 'polyfill') {
+                const expectedPolyfill = POLYFILL_BACKED_OPS[kind];
+                if (!expectedPolyfill) {
+                    acc.error(`hal/${category}/op/${kind}/polyfill-not-recognized`, `hal.${category}.ops.${kind}`, `op "${kind}" declared "polyfill" but is not in POLYFILL_BACKED_OPS. Either add it to packages/cuttlefish/src/api/shared/framework-manifest.ts or use a different status.`, kind);
+                    continue;
+                }
+                const emitted = manifest.polyfills.emitted.map((p) => p.id);
+                if (!emitted.includes(expectedPolyfill)) {
+                    acc.error(`hal/${category}/op/${kind}/polyfill-not-declared`, `hal.${category}.ops.${kind}`, `op "${kind}" declared "polyfill" (backed by "${expectedPolyfill}") but "${expectedPolyfill}" is not in polyfills.emitted. Add it, or remove this op from the polyfill status.`, kind);
+                }
+                continue;
+            }
+            const res = probeResolve(ctx.strategy, kind);
+            const lowers = statusFromResolution(res) === 'lowers';
+            if (status === 'supported' && !lowers) {
+                acc.error(`hal/${category}/op/${kind}/status-mismatch`, `hal.${category}.ops.${kind}`, `op "${kind}" declared "supported" but resolver returned ${res}. Either implement the lowering or change the op status.`, kind);
+            }
+            else if (status === 'stub' && !lowers) {
+                acc.error(`hal/${category}/op/${kind}/status-mismatch`, `hal.${category}.ops.${kind}`, `op "${kind}" declared "stub" but resolver emitted nothing (${res}). Either emit something or change to "unsupported".`, kind);
+            }
+            else if (status === 'unsupported' && lowers) {
+                acc.error(`hal/${category}/op/${kind}/status-mismatch`, `hal.${category}.ops.${kind}`, `op "${kind}" declared "unsupported" but resolver actually lowers (${res}). Either mark it supported or remove the lowering.`, kind);
+            }
+        }
+        // Category-level summary check.
+        if (declaration.supported) {
+            // If every op is probe-inconclusive, we can't verify the supported
+            // claim at all — skip rather than false-positive.
+            const hasVerifiable = knownKinds.some((k) => declaration.ops[k] !== 'probe-inconclusive');
+            if (hasVerifiable) {
+                const anyLowersOrInconclusive = knownKinds.some((k) => {
+                    if (declaration.ops[k] === 'probe-inconclusive')
+                        return true;
+                    if (declaration.ops[k] === 'polyfill')
+                        return true;
+                    return statusFromResolution(probeResolve(ctx.strategy, k)) === 'lowers';
+                });
+                if (!anyLowersOrInconclusive) {
+                    acc.error(`hal/${category}/declared-supported-but-undefined`, `hal.${category}`, `manifest.hal.${category}.supported is true but resolver returns undefined for every verifiable op kind. Change supported to false with unsupportedReason, or implement the lowering.`, category);
+                }
+            }
+        }
+        else {
+            // supported: false. Ignore probe-inconclusive and polyfill ops when
+            // checking "does it actually lower?" — polyfill ops legitimately
+            // return undefined from the HAL resolver.
+            const anyLowers = knownKinds.some((k) => {
+                if (declaration.ops[k] === 'probe-inconclusive')
+                    return false;
+                if (declaration.ops[k] === 'polyfill')
+                    return false;
+                return statusFromResolution(probeResolve(ctx.strategy, k)) === 'lowers';
+            });
+            if (anyLowers) {
+                acc.error(`hal/${category}/declared-unsupported-but-actually-lowers`, `hal.${category}`, `manifest.hal.${category}.supported is false but resolver lowers at least one verifiable op. Either mark supported: true or override the resolver to throw/return undefined.`, category);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Category D — polyfills
+// ---------------------------------------------------------------------------
+function validatePolyfills(manifest, ctx, acc) {
+    const strat = ctx.strategy;
+    // A polyfill is "produced" if either generateNativePolyfills OR
+    // nativePolyfills mentions it. generateNativePolyfills filters by program
+    // analysis (may omit polyfills not needed for the empty probe program);
+    // nativePolyfills is the unconditional set the strategy handles natively.
+    // Unioning both gives the true picture of what the strategy claims to emit.
+    const produced = new Set();
+    try {
+        const irs = strat.generateNativePolyfills?.({ kind: 'program', modules: [], classes: [], functions: [] }, undefined) ?? [];
+        for (const ir of irs)
+            produced.add(ir.id);
+    }
+    catch {
+        // generateNativePolyfills may throw on synthetic input; that's fine.
+    }
+    try {
+        const ids = strat.nativePolyfills?.() ?? new Set();
+        for (const id of ids)
+            produced.add(id);
+    }
+    catch {
+        // nativePolyfills is optional.
+    }
+    for (const declared of manifest.polyfills.emitted) {
+        if (!produced.has(declared.id)) {
+            acc.error(`polyfill/${declared.id}/declared-but-not-emitted`, `polyfills.emitted.${declared.id}`, `polyfill "${declared.id}" declared emitted but generateNativePolyfills/nativePolyfills did not produce it.`, declared.id);
+        }
+    }
+    for (const suppressed of manifest.polyfills.suppressed) {
+        if (produced.has(suppressed.id)) {
+            acc.error(`polyfill/${suppressed.id}/declared-suppressed-but-emitted`, `polyfills.suppressed.${suppressed.id}`, `polyfill "${suppressed.id}" declared suppressed but the strategy actually emits it.`, suppressed.id);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Category E — toolchain
+// ---------------------------------------------------------------------------
+function validateToolchain(manifest, ctx, acc) {
+    const ops = manifest.toolchain.operations;
+    if (!ops.compile) {
+        acc.error('toolchain/compile/required', 'toolchain.operations.compile', 'toolchain.operations.compile must be true (LoadedFramework contract requires a compile implementation).', 'compile');
+    }
+    const tc = ctx.toolchain;
+    if (tc) {
+        const checks = [
+            ['prepare', ops.prepare],
+            ['compile', ops.compile],
+            ['upload', ops.upload],
+            ['monitor', ops.monitor],
+        ];
+        for (const [op, declared] of checks) {
+            if (declared && typeof tc[op] !== 'function') {
+                acc.error(`toolchain/${op}/declared-but-missing`, `toolchain.operations.${op}`, `operation "${op}" declared true but is not a function on the loaded Toolchain.`, op);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Category F — library resolution
+// ---------------------------------------------------------------------------
+function validateLibraryResolution(manifest, ctx, acc) {
+    if (!manifest.libraryResolution)
+        return;
+    const lr = manifest.libraryResolution;
+    const checks = [
+        ['isFrameworkLibraryImport', lr.isFrameworkLibraryImport],
+        ['getFrameworkLibraryHeaderName', lr.getFrameworkLibraryHeaderName],
+        ['buildClassNameMap', lr.buildClassNameMap],
+        ['tryGenerateLibDecl', lr.tryGenerateLibDecl],
+    ];
+    for (const [name, declared] of checks) {
+        if (declared && typeof ctx.moduleExports[name] !== 'function') {
+            acc.error(`library-resolution/${name}/declared-but-not-exported`, `libraryResolution.${name}`, `"${name}" declared true but not exported from the framework package index.`, name);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Category G — type emission
+// ---------------------------------------------------------------------------
+function validateTypeEmission(manifest, ctx, acc) {
+    const te = manifest.typeEmission;
+    const strat = ctx.strategy;
+    const fieldChecks = [
+        ['mathHeader', te.mathHeader, strat.mathHeader()],
+        ['needsStdString', te.needsStdString, strat.needsStdString()],
+        ['needsStdVector', te.needsStdVector, strat.needsStdVector()],
+        ['needsIostream', te.needsIostream, strat.needsIostream()],
+        ['needsStdFunction', te.needsStdFunction, strat.needsStdFunction()],
+    ];
+    for (const [field, declared, actual] of fieldChecks) {
+        if (declared !== actual) {
+            acc.error(`type-emission/${field}/mismatch`, `typeEmission.${field}`, `manifest declares ${field}=${JSON.stringify(declared)} but strategy returns ${JSON.stringify(actual)}.`, field);
+        }
+    }
+    const actualStdlib = strat.getStdLibSupport();
+    const declaredStdlib = te.stdlibSupport;
+    const stdlibEqual = actualStdlib.hasVector === declaredStdlib.hasVector &&
+        actualStdlib.hasString === declaredStdlib.hasString &&
+        actualStdlib.hasIostream === declaredStdlib.hasIostream &&
+        actualStdlib.hasExceptions === declaredStdlib.hasExceptions &&
+        actualStdlib.hasRTTI === declaredStdlib.hasRTTI &&
+        actualStdlib.recommendedArrayImpl === declaredStdlib.recommendedArrayImpl &&
+        actualStdlib.recommendedStringImpl === declaredStdlib.recommendedStringImpl;
+    if (!stdlibEqual) {
+        acc.error('type-emission/stdlib-support-mismatch', 'typeEmission.stdlibSupport', `manifest stdlibSupport does not match strategy.getStdLibSupport() return.`);
+    }
+    // Ambient types
+    const emittedAmbient = new Set();
+    try {
+        const decls = strat.ambientTypeDeclarations?.() ?? [];
+        for (const d of decls) {
+            if (typeof d === 'string') {
+                // Match all ambient declarations in the string: interface/type/class NAME
+                // and const NAME: (Arduino/AVR/ESP32 emit `const Timing: {...}` etc.).
+                const matches = [...d.matchAll(/\b(?:interface|type|class)\s+([A-Za-z_$][\w$]*)/g)];
+                for (const m of matches)
+                    emittedAmbient.add(m[1]);
+                const constMatches = [...d.matchAll(/\bconst\s+([A-Za-z_$][\w$]*)\s*:/g)];
+                for (const m of constMatches)
+                    emittedAmbient.add(m[1]);
+            }
+            else if (d && typeof d === 'object' && 'name' in d) {
+                emittedAmbient.add(String(d.name));
+            }
+        }
+    }
+    catch {
+        // ambientTypeDeclarations is optional and may require a context.
+    }
+    for (const declared of manifest.ambientTypes) {
+        if (!emittedAmbient.has(declared)) {
+            acc.error(`ambient-types/${declared}/declared-but-not-emitted`, `ambientTypes.${declared}`, `ambient type "${declared}" declared but not found in ambientTypeDeclarations() output.`, declared);
+        }
+    }
+    for (const emitted of emittedAmbient) {
+        if (!manifest.ambientTypes.includes(emitted)) {
+            acc.warning(`ambient-types/${emitted}/emitted-but-undeclared`, 'ambientTypes', `ambient type "${emitted}" emitted by strategy but not listed in manifest. Consider adding it.`, emitted);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Category H — conformance
+// ---------------------------------------------------------------------------
+function validateConformance(manifest, ctx, acc) {
+    for (const group of manifest.conformance.hardwareTestGroups) {
+        const filePath = path.join(ctx.packageRoot, 'tests', `${group}.test.ts`);
+        if (!fs.existsSync(filePath)) {
+            acc.error(`conformance/hardware/${group}/file-not-found`, `conformance.hardwareTestGroups.${group}`, `hardware test group "${group}" listed but ${filePath} does not exist.`, group);
+        }
+    }
+    for (const name of manifest.conformance.halResolutionTests) {
+        // Test dir convention is tests/packages/<package-dir-name>/hal-resolution/.
+        // Package dir name is the last segment of packageName (e.g.
+        // "@typecad/framework-esp32" -> "framework-esp32"), not frameworkId.
+        const packageDirName = manifest.packageName.split('/').pop() ?? manifest.frameworkId;
+        const filePath = path.join(ctx.repoTestsDir, 'packages', packageDirName, 'hal-resolution', `${name}.test.ts`);
+        if (!fs.existsSync(filePath)) {
+            acc.error(`conformance/hal/${name}/file-not-found`, `conformance.halResolutionTests.${name}`, `HAL resolution test "${name}" listed but ${filePath} does not exist.`, name);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export function validateFrameworkManifest(manifest, ctx) {
+    const acc = new Accumulator();
+    validateIdentity(manifest, ctx, acc);
+    validateEntrypoint(manifest, ctx, acc);
+    validateHalCoverage(manifest, ctx, acc);
+    validatePolyfills(manifest, ctx, acc);
+    validateToolchain(manifest, ctx, acc);
+    validateLibraryResolution(manifest, ctx, acc);
+    validateTypeEmission(manifest, ctx, acc);
+    validateConformance(manifest, ctx, acc);
+    return {
+        valid: acc.errors.length === 0,
+        errors: acc.errors,
+        warnings: acc.warnings,
+    };
+}

package/dist/cli-utils.d.ts

@@ -13,6 +13,7 @@ export declare function printDiagnostics(diagnostics: Array<Diagnostic | {
     line?: number;
     column?: number;
     code?: string;
+    filePath?: string;
     sourceLine?: string;
 }>): void;
 /**

package/dist/cli-utils.js

@@ -50,6 +50,7 @@ export function printDiagnostics(diagnostics) {
     for (const diagnostic of diagnostics) {
         const position = diagnostic.line && diagnostic.column ? chalk.gray(`(${diagnostic.line},${diagnostic.column})`) : "";
         const code = diagnostic.code ? chalk.gray(` [${diagnostic.code}]`) : "";
+        const file = 'filePath' in diagnostic && diagnostic.filePath ? chalk.cyan(diagnostic.filePath) : "";
         let severityLabel;
         let hintColor;
         if (diagnostic.severity === "error") {
@@ -65,7 +66,8 @@ export function printDiagnostics(diagnostics) {
             hintColor = chalk.cyan;
         }
         const location = position ? ` ${position}` : "";
-        const header = `${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
+        const filePrefix = file ? `${file} ` : "";
+        const header = `${filePrefix}${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
         if (diagnostic.severity === "error") {
             console.error(header);
         }