@typecad/cuttlefish 1.0.0-alpha.6 → 1.0.0-alpha.8

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

@@ -0,0 +1,494 @@
+// ---------------------------------------------------------------------------
+// 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.'],
+    rmt: ['rmt.'],
+    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.'],
+    ble: ['ble.'],
+    random: ['random.'],
+    fs: ['fs.'],
+    mdns: ['mdns.'],
+    mqtt: ['mqtt.'],
+    ota: ['ota.'],
+    temp: ['temp.'],
+    hwtimer: ['hwtimer.'],
+    capacitive: ['capacitive.'],
+    // Unimplemented-but-recognized categories: each framework may declare these
+    // as unsupported in its manifest so the coverage matrix records them as a
+    // roadmap. The validator probes the resolver and confirms it does NOT lower
+    // them (consistent with the 'unsupported' status).
+    i2s: ['i2s.'],
+    twai: ['twai.'],
+    usb: ['usb.'],
+    eth: ['eth.'],
+    espnow: ['espnow.'],
+    crypto: ['crypto.'],
+    pcnt: ['pcnt.'],
+    mcpwm: ['mcpwm.'],
+    // Worker offload + snprintf raw-escape: recognized categories. Frameworks
+    // that lower worker.* declare it supported; snprintf.emit is a raw escape
+    // hatch (declared unsupported by frameworks that don't special-case it).
+    worker: ['worker.'],
+    snprintf: ['snprintf.'],
+};
+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 }] },
+    // fs.* require a path (and content for write_text).
+    'fs.read_text': { path: '/sdcard/x.txt' },
+    'fs.write_text': { path: '/sdcard/x.txt', content: 'hi' },
+    'fs.exists': { path: '/sdcard/x.txt' },
+    'fs.remove': { path: '/sdcard/x.txt' },
+    // random.range requires min/max.
+    'random.range': { min: 0, max: 10 },
+    // mdns.add_service requires instance/proto/port.
+    'mdns.start': { hostname: 'h' },
+    'mdns.set_hostname': { name: 'h' },
+    'mdns.add_service': { instance: 'i', proto: '_tcp', port: 80 },
+    // mqtt.connect requires brokerUri/clientId; mqtt.publish requires topic/data.
+    'mqtt.connect': { brokerUri: 'mqtt://b', clientId: 'c' },
+    'mqtt.on_message': { handler: 'cb' },
+    'mqtt.subscribe': { topic: 't' },
+    'mqtt.publish': { topic: 't', data: 'd' },
+    // wifi.on_event requires an event + handler. Probe with 'connect'.
+    // Without a payload the probe sends event=undefined and a 'supported'
+    // declaration would false-fail as "resolver returned undefined".
+    'wifi.on_event': { event: 'connect', handler: 'cb' },
+    // ota.from_url requires url; ota.write requires chunk.
+    'ota.from_url': { url: 'https://x' },
+    'ota.write': { chunk: 'buf' },
+    // hwtimer.* require an instance (and hz/handler).
+    'hwtimer.set_frequency': { instance: 0, hz: 1000 },
+    'hwtimer.on_overflow': { instance: 0, handler: 'cb' },
+    'hwtimer.start': { instance: 0 },
+    'hwtimer.stop': { instance: 0 },
+    // capacitive.read requires pin.
+    'capacitive.read': { pin: 4 },
+};
+// 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 C2 — HAL completeness
+// ---------------------------------------------------------------------------
+/**
+ * Verify every known HAL category appears in manifest.hal. validateHalCoverage
+ * only audits categories the manifest declares; a category omitted entirely is
+ * invisible to it (and to the per-op check). This step closes that hole: each
+ * category in CATEGORY_PREFIXES must be accounted for, even as unsupported.
+ * `raw` is excluded — it is the schema-level escape hatch, not a real category,
+ * and is not in CATEGORY_PREFIXES.
+ */
+function validateHalCompleteness(manifest, _ctx, acc) {
+    const declared = new Set(Object.keys(manifest.hal));
+    for (const category of Object.keys(CATEGORY_PREFIXES)) {
+        if (!declared.has(category)) {
+            acc.error(`hal/${category}/category-undeclared`, `manifest.hal.${category}`, `manifest.hal is missing the "${category}" category. Add a block declaring it (supported: true/false with ops, or unsupported with unsupportedReason).`, 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);
+    validateHalCompleteness(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/api/shared/worker-runtime-polyfill.d.ts

@@ -0,0 +1,22 @@
+import type { ProgramIR } from "../index.js";
+import type { RuntimePolyfillIR } from "./index.js";
+import type { PlatformStrategy } from "./platform-strategy.js";
+import type { WorkerBacking } from "./worker-runtime.js";
+/**
+ * Build a RuntimePolyfillIR for the worker-offload runtime, when the framework
+ * supplies worker backing via its PlatformAsyncStrategy hooks
+ * (workerSpawnLines / workerSignalDoneExpr / workerIsDoneExpr).
+ *
+ * The polyfill carries only the slot table + __tc_worker_submit/done contract
+ * with the per-framework primitives injected from the strategy hooks. STL-free
+ * so it links on minimal-libc targets (Zephyr). Returns null if the strategy
+ * supplies no backing (worker offload unsupported there) — in which case
+ * worker.* ops resolve to unsupported.
+ *
+ * Callers gate this on the program actually using worker.* ops
+ * (ProgramAnalysisResult.usesWorker); the producer does not re-scan.
+ */
+export declare function buildWorkerRuntimePolyfill(_program: ProgramIR, strategy: PlatformStrategy, backing: WorkerBacking, options?: {
+    poolSize?: number;
+    stackSize?: number;
+}): RuntimePolyfillIR | null;

package/dist/api/shared/worker-runtime-polyfill.js

@@ -0,0 +1,34 @@
+import { generateWorkerRuntime } from "./worker-runtime.js";
+/**
+ * Build a RuntimePolyfillIR for the worker-offload runtime, when the framework
+ * supplies worker backing via its PlatformAsyncStrategy hooks
+ * (workerSpawnLines / workerSignalDoneExpr / workerIsDoneExpr).
+ *
+ * The polyfill carries only the slot table + __tc_worker_submit/done contract
+ * with the per-framework primitives injected from the strategy hooks. STL-free
+ * so it links on minimal-libc targets (Zephyr). Returns null if the strategy
+ * supplies no backing (worker offload unsupported there) — in which case
+ * worker.* ops resolve to unsupported.
+ *
+ * Callers gate this on the program actually using worker.* ops
+ * (ProgramAnalysisResult.usesWorker); the producer does not re-scan.
+ */
+export function buildWorkerRuntimePolyfill(_program, strategy, backing, options = {}) {
+    // The backing is authoritative: it is constructed by the framework from its
+    // own hooks. If a framework supplies no backing (worker offload unsupported),
+    // it should not call this producer.
+    const runtime = generateWorkerRuntime(backing, options);
+    if (!runtime)
+        return null;
+    return {
+        kind: "polyfill",
+        id: "worker_runtime",
+        domain: "embedded",
+        requiredIncludes: backing.requiredIncludes,
+        forwardDeclarations: backing.declarations ?? [],
+        helperStructs: [runtime],
+        helperFunctions: [],
+        shimMacros: [],
+        dependencies: [],
+    };
+}

package/dist/api/shared/worker-runtime.d.ts

@@ -0,0 +1,69 @@
+export interface WorkerRuntimeOptions {
+    /** Number of fixed worker slots in the pool. Default 4. */
+    poolSize?: number;
+    /** Per-slot worker stack size in bytes (ESP32). Default 8192. */
+    stackSize?: number;
+}
+/**
+ * Per-framework backing primitives injected into the shared contract.
+ * Undefined fields mean "unsupported" and the runtime is not emitted.
+ */
+export interface WorkerBacking {
+    /**
+     * Statements that spawn the worker trampoline for slot `handleId`.
+     *
+     * `trampolineName` is the C++ symbol of the per-slot worker function the
+     * shared runtime generated (it reads fn/arg from the slot, runs them, then
+     * signals completion). `waiterExpr` is the C++ lvalue the backing should set
+     * to the current waiter handle before spawning (the shared runtime reads it
+     * via signalDoneExpr/isDoneExpr).
+     *
+     * The shared runtime has already stored the submitted fn/arg into the slot
+     * and cleared `done` before this runs; the backing need only record the
+     * waiter and spawn `trampolineName`.
+     */
+    spawnLines: (handleId: number, trampolineName: string, waiterExpr: string) => string[];
+    /** Expression the worker calls after finishing + writing outputs (barrier). */
+    signalDoneExpr: (handleId: number) => string;
+    /** Boolean expression polled by __tc_worker_done (observes the barrier). */
+    isDoneExpr: (handleId: number) => string;
+    /** C++ headers required by the primitives (e.g. '<freertos/FreeRTOS.h>'). */
+    requiredIncludes: string[];
+    /** Any backing declarations (e.g. semaphore objects) emitted before the pool. */
+    declarations?: string[];
+    /**
+     * Per-slot backing declarations emitted inside the namespace, one call per
+     * slot, before the submit/done functions. Used by backings that need a named
+     * per-slot object bound to the trampoline at definition time — e.g. Zephyr's
+     * `K_WORK_DEFINE(_work_<i>, __tc_worker_fn_<i>)` + a per-slot semaphore.
+     * `trampolineName` is the per-slot worker symbol the shared runtime emitted.
+     */
+    slotDeclarations?: (handleId: number, trampolineName: string) => string[];
+}
+/**
+ * Generate the worker-offload runtime C++ for a framework that supplies a
+ * backing. Returns null if `backing` is null (unsupported on this framework).
+ *
+ * The emitted code defines, for each slot i in [0, poolSize):
+ *   - a worker trampoline __tc_worker_fn_i(void* arg) that runs the recorded
+ *     fn and then signals completion via signalDoneExpr,
+ *   - __tc_worker_submit(i, fn, arg) — records the waiter, clears done, spawns,
+ *   - __tc_worker_done(i) — poll predicate.
+ *
+ * AUTOSAR C++14: fixed-width types, static_cast, final structs, no STL, no heap.
+ */
+export declare function generateWorkerRuntime(backing: WorkerBacking | null, options?: WorkerRuntimeOptions): string | null;
+/**
+ * Resolve a HAL worker.* op to C++ against the shared contract.
+ * Returns undefined for ops the caller did not lower (unsupported).
+ *
+ * Note: the worker function itself (fnRef) and its argument (argRef) come from
+ * the IR as flat-scalar strings (per the hal-op-ir flat-fields contract). The
+ * lowering emits a straight call into __tc_worker_submit / __tc_worker_done.
+ */
+export declare function lowerWorkerOp(op: {
+    operation: string;
+}): {
+    code?: string;
+    expression?: string;
+} | undefined;