@typecad/framework-zephyr 1.0.0-alpha.18 → 1.0.0-alpha.19

package/dist/framework.manifest.js

@@ -96,6 +96,85 @@ export default defineFrameworkManifest({
                 'pwm.set_pulse': 'supported',
                 'pwm.set_duty': 'supported',
                 'pwm.set_period': 'supported',
+                // Servo (hal/servo.ts): calibrated 50 Hz sugar on the same channel —
+                // clamping and the angle→pulse mapping run in the lowered C++.
+                'pwm.servo_us': 'supported',
+                'pwm.servo_angle': 'supported',
+                'pwm.servo_idle': 'supported',
+            },
+        },
+        // ── Supported: LED strip (ws2812-spi over led_strip API) ───────────────
+        strip: {
+            // DAC discipline: lowers on every board with a wired SPI controller;
+            // a board with none lowers to a comment (profileDiagnostics flags it).
+            supported: true,
+            partialCoverage: true,
+            ops: {
+                // Strip (hal/strip.ts): buffer edits + one-wire-transaction show.
+                'strip.set_pixel': 'supported',
+                'strip.fill': 'supported',
+                'strip.show': 'supported',
+            },
+        },
+        // ── Board-gated: USB HID keyboard/mouse (zephyr,hid-device) ───────────
+        hid: {
+            // Same BOARD-GATED shape as usb below: the lowering only fires when
+            // the board's manifest carries zephyr.usb.* — the manifest probe runs
+            // with no board, so the honest declaration is unsupported here. The
+            // board module exports Keyboard/Mouse only on USB-capable boards
+            // (the module-resolution gate); one HID interface per program (the v1
+            // ceiling — mixing the two classes is a compile-time #error).
+            supported: false,
+            unsupportedReason: 'Board-gated: HID lowers only on boards whose DTS enables the USB device controller (boardgen emits zephyr.usb.* from the catalog).',
+            partialCoverage: false,
+            ops: unsupportedOps('hid.'),
+        },
+        // ── Supported: CAN bus (harvested can@ controllers) ────────────────────
+        can: {
+            supported: true,
+            partialCoverage: true,
+            ops: {
+                // Classic CAN (11/29-bit ids, ≤8-byte payloads). Partial: CAN-FD,
+                // bitrate data phase, and RTR frames are not surfaced in v1.
+                'can.begin': 'supported',
+                'can.send': 'supported',
+                'can.on_receive': 'supported',
+            },
+        },
+        // ── Supported: wall-clock time (rtc alias / counter shim) ─────────────
+        clock: {
+            supported: true,
+            partialCoverage: true,
+            ops: {
+                // set/now in Unix epoch seconds. Partial: v1 semantics are
+                // session-scoped on counter-backed boards — only hardware-calendar
+                // aliases persist across power loss.
+                'clock.set': 'supported',
+                'clock.now': 'supported',
+            },
+        },
+        // ── Supported: explicit power-state entry (sys_poweroff) ───────────────
+        power: {
+            supported: true,
+            partialCoverage: true,
+            ops: {
+                // Soft-off entry — never returns; wake by reset or a board wake
+                // source. Partial: the light states belong to the idle policy, not
+                // the app (no op surface for them in v1).
+                'power.off': 'supported',
+                // off_for arms the RTC wake timer before soft-off — ESP32 family
+                // (the harvested rtc_timer fact); boards without the fact lower
+                // to a comment naming the limitation (the DAC discipline).
+                'power.off_for': 'supported',
+            },
+        },
+        // ── Supported: GPIO key matrix (gpio-kbd-matrix, input subsystem) ─────
+        matrix: {
+            supported: true,
+            partialCoverage: false,
+            ops: {
+                // Matrix (hal/matrix.ts): (row, col, pressed) trampoline.
+                'matrix.on_key': 'supported',
             },
         },
         // ── Supported: ADC (SAADC via adc_read + channel setup) ────────────────
@@ -141,6 +220,12 @@ export default defineFrameworkManifest({
                 'i2c.reg_read': 'supported',
                 'i2c.reg_update': 'supported',
                 'i2c.dev_write': 'supported',
+                // I2C responder (hal/i2c-responder.ts): this board as an I2C target.
+                'i2c.resp_on_receive': 'supported',
+                'i2c.resp_on_request': 'supported',
+                'i2c.resp_available': 'supported',
+                'i2c.resp_read': 'supported',
+                'i2c.resp_write': 'supported',
             },
         },
         spi: {
@@ -276,11 +361,25 @@ export default defineFrameworkManifest({
             partialCoverage: true,
             // Partial: mono profiles (ssd1306-zephyr) drive display.* ops via the
             // direct GFX runtime only — no CuttlefishGFX UI rendering path. The
-            // ILI9341 UI adapter shares the ST7796S direct-drive transport with a
-            // per-controller init table (16-bit RGB565 wire format); hardware-tuned
-            // on ST7796S only. E-ink panels are out of scope at this time.
-            unsupportedReason: 'Mono panels (ssd1306) are direct-op only (no UI rendering); ili9341 UI path is ported but not yet hardware-verified; e-ink is out of scope at this time.',
-            drivers: ['ili9341-zephyr', 'st7796-zephyr', 'ssd1306-zephyr'],
+            // direct-spi UI adapters (st7796-zephyr, ili9341-zephyr) drive the
+            // panel over spi_write with per-controller Adafruit init tables;
+            // st7796-zephyr is the full-fidelity path on the clone rig
+            // (18-bit mode, hardware-verified incl. colors + touch interaction;
+            // the demo needs psram:'opi' for full rendering and resetPin for the
+            // touch module's power enable). The zephyr-display transport rides
+            // in-tree panel drivers through Zephyr's display API: st7796s via an
+            // adapter-emitted CS-holding mipi-dbi host — colors hardware-confirmed
+            // correct on the rig with the byte-swap + CS-hold knobs (the stock
+            // bridge corrupts bursts on this clone; a ladder test observed slight
+            // uniform dimness vs the direct path's 18-bit mode, so direct remains
+            // the max-fidelity option there); ili9341 via the stock mipi-dbi-spi
+            // bridge is compile/link-verified only. Drop-in configs (display.driver
+            // = any bound compatible + geometry + quirk flags) ride the same path.
+            // Touch: FT6336U through the input subsystem (in-tree driver,
+            // polling mode, hardware-verified); XPT2046 stays on the raw adapter
+            // (the in-tree driver's DT scaling would double-apply calibration).
+            unsupportedReason: 'Mono panels (ssd1306) are direct-op only (no UI rendering); the direct-spi ili9341 UI path is not yet hardware-verified; the zephyr-display transport is hue-verified but 16-bit-brightness-limited on the clone st7796s (use direct-spi there) and compile-verified on ili9341; e-ink is out of scope at this time.',
+            drivers: ['ili9341-zephyr', 'ili9341-zephyr-display', 'st7796-zephyr', 'st7796-zephyr-display', 'ssd1306-zephyr'],
             colorFormat: 'rgb565',
             ops: {
                 'display.init': 'supported',
@@ -388,10 +487,13 @@ export default defineFrameworkManifest({
             },
         },
         i2s: {
-            supported: false,
-            unsupportedReason: 'No I2S / digital audio lowering on Zephyr.',
-            partialCoverage: false,
-            ops: unsupportedOps('i2s.'),
+            supported: true,
+            partialCoverage: true,
+            ops: {
+                'i2s.write': 'supported',
+                'i2s.read': 'supported',
+                'i2s.read_at': 'supported',
+            },
         },
         twai: {
             supported: false,
@@ -509,6 +611,17 @@ export default defineFrameworkManifest({
     // previews how the configured board target resolves for that version.
     doctor: { available: true },
     // `typecad-hal licenses` enumerates the Zephyr kernel + west manifest projects
-    // and resolves each one's SPDX license (mirrors framework-arduino).
+    // and resolves each one's SPDX license.
     licenses: { available: true },
+    // `typecad-hal sbom` emits a build-true SBOM (CycloneDX 1.6 / SPDX 2.3):
+    // linked west modules + kernel with commit SHAs and licenses, the hashed
+    // firmware artifact, the board, and the toolchain in `formulation`;
+    // --check/--diff gate the record against the build.
+    sbom: { available: true },
+    // `typecad-hal audit` evaluates the last build's merged Kconfig against a
+    // security baseline (shell/console exposure, entropy, watchdog, hard-coded
+    // credentials...), with committed waivers (.typecad-hal/audit-waivers.json)
+    // recorded as deviations and a machine-readable sidecar
+    // (<buildDir>/security-audit.json).
+    audit: { available: true },
 });

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { bossacTouchReset } from './toolchain/bossac-touch.js';
 export { writeProjectDebugArtifacts } from './toolchain/debug-config.js';
 export { runDoctor as doctor } from './doctor.js';
 export { runLicensesPresenter as licenses } from './licenses.js';
+export { runSbomPresenter as sbom } from './sbom.js';
+export { runAuditPresenter as audit } from './audit.js';
 export { setActiveChip, getActiveChip, NO_BOARD_CHIP, } from './chips/index.js';
 export type { ZephyrChipDescriptor, ZephyrGpioDtSpec, } from './chips/types.js';
 export { syncBoardCatalog, ensureFreshBoardCatalog, loadBoardCatalogOverlay, resetBoardCatalogOverlayCache, } from './sdk/board-catalog-sync.js';

package/dist/index.js

@@ -22,8 +22,16 @@ export { runDoctor as doctor } from './doctor.js';
 // `typecad-hal licenses` — enumerate the Zephyr kernel + west manifest projects
 // and resolve each one's SPDX license. Re-exported under the dispatcher-facing
 // alias `licenses` so the loader picks it up as mod.licenses (see
-// framework-package.ts). Mirrors framework-arduino's presenter.
+// framework-package.ts).
 export { runLicensesPresenter as licenses } from './licenses.js';
+// `typecad-hal sbom` — emit/verify a build-true software bill of materials
+// (CycloneDX 1.6 / SPDX 2.3). Re-exported under the dispatcher-facing alias
+// `sbom` so the loader picks it up as mod.sbom (see framework-package.ts).
+export { runSbomPresenter as sbom } from './sbom.js';
+// `typecad-hal audit` — evaluate the last build's merged Kconfig against the
+// security baseline, with committed waivers recorded as deviations.
+// Re-exported under the dispatcher-facing alias `audit` (same loader pattern).
+export { runAuditPresenter as audit } from './audit.js';
 // Chip descriptor cache (the lowering's resolved-board view; no curated
 // registry — every board reconstructs from its generated manifest).
 export { setActiveChip, getActiveChip, NO_BOARD_CHIP, } from './chips/index.js';

package/dist/licenses.js

@@ -27,36 +27,7 @@ import { loadTypecadConfig } from '@typecad/cuttlefish/config-loader';
 import { resolveLibraryLicense, RISK_RANK, riskBracket, statusMark, countByRisk, } from '@typecad/cuttlefish/api/shared';
 import { discoverWest } from './toolchain/west-discover.js';
 import { westSpawn } from './toolchain/west-spawn.js';
-// ---------------------------------------------------------------------------
-// Linked-module filtering (project scope)
-// ---------------------------------------------------------------------------
-/** Normalize a path for case-insensitive, separator-agnostic comparison. */
-function norm(p) {
-    return p.split('\\').join('/').toLowerCase();
-}
-/**
- * Filter the west manifest to the modules whose sources were compiled in the
- * last build. A module is "linked" iff some compiled translation unit lives
- * under its abspath. If the build data is unparseable, no filtering is applied
- * (degrade to listing all modules rather than reporting nothing).
- */
-function filterLinkedModules(ccText, modules) {
-    let arr;
-    try {
-        arr = JSON.parse(ccText);
-    }
-    catch {
-        return modules;
-    }
-    if (!Array.isArray(arr))
-        return modules;
-    // One normalized blob of every compiled source path; membership is then a
-    // substring check per module (O(modules) after an O(TUs) join).
-    const blob = arr
-        .map((e) => norm(typeof e?.file === 'string' ? e.file : ''))
-        .join('\n');
-    return modules.filter((m) => blob.includes(norm(m.abspath) + '/'));
-}
+import { filterLinkedModules, findCompileCommandsPath } from './west-inventory.js';
 // ---------------------------------------------------------------------------
 // scanZephyrLicenses — enumerate + resolve the workspace dependency set
 // ---------------------------------------------------------------------------
@@ -139,59 +110,6 @@ export function scanZephyrLicenses(runner, all = false) {
 // ---------------------------------------------------------------------------
 // Default runner — wires seams to discoverWest + westSpawn + fs
 // ---------------------------------------------------------------------------
-/**
- * Find the build's compile_commands.json under cwd. Cuttlefish's Zephyr project
- * root is the transpile output dir (e.g. `<cwd>/src/out`), so the build dir is
- * `<root>/build` — not necessarily `<cwd>/build`. Check the common layouts,
- * then fall back to a bounded search (skipping node_modules/.git/dist).
- */
-function findCompileCommandsText(readFile, readdir) {
-    const direct = [
-        path.join(process.cwd(), 'build', 'compile_commands.json'),
-        path.join(process.cwd(), 'out', 'build', 'compile_commands.json'),
-        path.join(process.cwd(), 'src', 'out', 'build', 'compile_commands.json'),
-    ];
-    for (const c of direct) {
-        const text = readFile(c);
-        if (text)
-            return text;
-    }
-    // Bounded recursive search for a build/compile_commands.json.
-    const isCc = (p) => {
-        const n = norm(p);
-        return n.endsWith('/build/compile_commands.json') || n.endsWith('\\build\\compile_commands.json');
-    };
-    let found;
-    const seen = new Set();
-    const walk = (dir, depth) => {
-        if (found || depth > 4 || seen.has(dir))
-            return;
-        seen.add(dir);
-        let entries;
-        try {
-            entries = readdir(dir);
-        }
-        catch {
-            return;
-        }
-        for (const e of entries) {
-            const full = path.join(dir, e);
-            if (e === 'compile_commands.json' && isCc(full)) {
-                found = full;
-                return;
-            }
-        }
-        for (const e of entries) {
-            if (found)
-                return;
-            if (e === 'node_modules' || e === '.git' || e === 'dist' || e.startsWith('.'))
-                continue;
-            walk(path.join(dir, e), depth + 1);
-        }
-    };
-    walk(process.cwd(), 0);
-    return found ? (readFile(found) ?? null) : null;
-}
 function defaultRunner() {
     const install = discoverWest();
     if (!install)
@@ -257,7 +175,10 @@ function defaultRunner() {
         topdir,
         listModules,
         zephyrBase,
-        compileCommands: () => findCompileCommandsText(readFile, readdir),
+        compileCommands: () => {
+            const p = findCompileCommandsPath(readFile, readdir);
+            return p ? (readFile(p) ?? null) : null;
+        },
         readFile,
         readdir,
     };

package/dist/lowering/can.d.ts

@@ -0,0 +1,25 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/** Which can.* verbs the program actually uses on a controller — the
+ *  init block emits only the state those verbs reference (Zephyr's -Werror
+ *  turns an unreferenced static function/variable into a build failure:
+ *  a send-only program must not carry the rx trampoline). */
+export interface CanUsage {
+    begin: boolean;
+    send: boolean;
+    onReceive: boolean;
+}
+/**
+ * Emit the per-controller CAN state: device handle, rx trampoline +
+ * handler slot, and the accept-all filters. Called from shimLines when the
+ * program uses can.* on this controller and the chip declares it.
+ */
+export declare function canInitLines(chip: ZephyrChipDescriptor, controllerIndex: number, usage: CanUsage): string[];
+/**
+ * Resolve a HAL can.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerCan(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/can.js

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// CAN lowering — Zephyr's can API over the harvested controller node
+//
+// The controller is addressed by its DT nodelabel (chip.can, the harvested
+// can@ node — ESP32 TWAI, STM32 bxCAN, NXP FlexCAN…). begin() applies
+// mode + bitrate + start in the required order (mode and bitrate need a
+// stopped controller); send() builds one can_frame and submits it with a
+// bounded timeout and no tx callback (blocking-send form); onReceive()
+// installs the accept-all filter whose trampoline carries the frame as
+// ten scalars — the Matrix discipline (ISR context, set-a-variable work).
+// ----------------------------------------------------------------------------
+/** The C variable names for a CAN controller's state. */
+function prefix(idx) {
+    return `__tc_can${idx}`;
+}
+/**
+ * Emit the per-controller CAN state: device handle, rx trampoline +
+ * handler slot, and the accept-all filters. Called from shimLines when the
+ * program uses can.* on this controller and the chip declares it.
+ */
+export function canInitLines(chip, controllerIndex, usage) {
+    const ctrl = chip.can?.controllers[controllerIndex];
+    if (!ctrl)
+        return [];
+    const p = prefix(controllerIndex);
+    const lines = [
+        '// CUTTLEFISH_CAN_BEGIN',
+        `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
+    ];
+    if (usage.begin) {
+        // Shim-scoped (not per call site): a second begin() anywhere in the
+        // program must not re-fire can_start on a started controller.
+        lines.push(`static bool ${p}_started = false;`);
+    }
+    if (usage.onReceive) {
+        lines.push(`static void (*${p}_rx)(double, double, double, double, double, double, double, double, double, double) = NULL;`, 
+        // dlc-bounded: drivers fill only data[0..dlc-1] — copy into a zeroed
+        // local so the handler's b0..b7 tail is zero, as the class documents.
+        'static void __tc_can_rx_trampoline(const struct device* dev, struct can_frame* frame, void* user_data) {', '    (void)dev;', '    (void)user_data;', `    if (${p}_rx != NULL) {`, '        uint8_t __tc_d[8] = { 0U, 0U, 0U, 0U, 0U, 0U, 0U, 0U };', '        for (uint32_t __tc_i = 0U; (__tc_i < 8U) && (__tc_i < static_cast<uint32_t>(frame->dlc)); ++__tc_i) { __tc_d[__tc_i] = frame->data[__tc_i]; }', `        ${p}_rx(static_cast<double>(frame->id), static_cast<double>(frame->dlc),`, `                          static_cast<double>(__tc_d[0]), static_cast<double>(__tc_d[1]),`, `                          static_cast<double>(__tc_d[2]), static_cast<double>(__tc_d[3]),`, `                          static_cast<double>(__tc_d[4]), static_cast<double>(__tc_d[5]),`, `                          static_cast<double>(__tc_d[6]), static_cast<double>(__tc_d[7]));`, '    }', '}', 
+        // Two accept-all filters: can_filter_matches_filter never delivers an
+        // IDE (29-bit) frame to a filter without CAN_FILTER_IDE — one filter
+        // per frame format, so extended sends are receivable too.
+        `static const struct can_filter ${p}_filter = { .id = 0U, .mask = 0U, .flags = 0U };`, `static const struct can_filter ${p}_filter_ext = { .id = 0U, .mask = 0U, .flags = CAN_FILTER_IDE };`, `static bool ${p}_filter_added = false;`);
+    }
+    if (usage.send) {
+        lines.push(`static void __tc_can_tx_done(const struct device* dev, int error, void* user_data) {`, '    (void)dev; (void)error; (void)user_data;', '}');
+    }
+    lines.push('// CUTTLEFISH_CAN_END');
+    return lines;
+}
+/**
+ * Resolve a HAL can.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerCan(op, chip) {
+    const o = op;
+    // DAC discipline: a board with no harvested can@ node lowers to a comment
+    // naming the constraint (the board gate already refuses the CAN import;
+    // this keeps the manifest probe and direct-lowering paths honest).
+    if (!chip.can || chip.can.controllers.length === 0) {
+        return { code: `/* ${op.operation}: this board's chip data declares no CAN controller (no harvested can@ node) */` };
+    }
+    const idx = Math.min(Number(o.instance ?? 0), chip.can.controllers.length - 1);
+    const p = prefix(idx);
+    const started = `${p}_started`;
+    switch (op.operation) {
+        case 'can.begin': {
+            // Mode and bitrate require a STOPPED controller — apply them before
+            // the start, and start exactly once. Failures printk (the loud-
+            // diagnostics policy): a CAN bus that never comes up is otherwise a
+            // silent hang at the first send.
+            return {
+                code: `{ int __tc_err; if (${o.loopback}) { __tc_err = can_set_mode(${p}_dev, CAN_MODE_LOOPBACK); if (__tc_err != 0) { printk("typecad-hal can: set_mode failed: %d\\n", __tc_err); } } __tc_err = can_set_bitrate(${p}_dev, ${o.hz}); if (__tc_err != 0) { printk("typecad-hal can: bitrate failed: %d\\n", __tc_err); } if (!${started}) { ${started} = true; __tc_err = can_start(${p}_dev); if (__tc_err != 0) { printk("typecad-hal can: start failed: %d\\n", __tc_err); } } }`,
+            };
+        }
+        case 'can.send': {
+            const bytes = (o.data ?? []);
+            if (bytes.length > 8) {
+                throw new Error(`CAN send: classic frames carry at most 8 bytes — got ${bytes.length}.`);
+            }
+            const assigns = bytes
+                .map((b, i) => `__tc_frame.data[${i}] = static_cast<uint8_t>(${b});`)
+                .join(' ');
+            return {
+                code: `{ struct can_frame __tc_frame = { 0 }; __tc_frame.id = static_cast<uint32_t>(${o.id}); __tc_frame.dlc = ${bytes.length}U; __tc_frame.flags = ${o.extended ? 'CAN_FRAME_IDE' : '0U'}; ${assigns} int __tc_err = can_send(${p}_dev, &__tc_frame, K_MSEC(100), __tc_can_tx_done, NULL); if (__tc_err != 0) { printk("typecad-hal can: send failed: %d\\n", __tc_err); } }`,
+            };
+        }
+        case 'can.on_receive': {
+            return {
+                code: `{ ${p}_rx = ${o.handler}; if (!${p}_filter_added) { ${p}_filter_added = true; (void)can_add_rx_filter(${p}_dev, __tc_can_rx_trampoline, NULL, &${p}_filter); (void)can_add_rx_filter(${p}_dev, __tc_can_rx_trampoline, NULL, &${p}_filter_ext); } }`,
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/clock.d.ts

@@ -0,0 +1,17 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/** The conversion helpers + device handle. Called from shimLines when the
+ *  program uses clock.* — each helper only when its consuming op appears
+ *  (a now()-only program must not carry the unused set() helper: -Werror
+ *  fails the build on unreferenced static functions). */
+export declare function clockInitLines(usage: {
+    set: boolean;
+    now: boolean;
+}): string[];
+/**
+ * Resolve a HAL clock.* op to Zephyr C++.
+ * Returns `{ code }` for set, `{ expression }` for now.
+ */
+export declare function lowerClock(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/clock.js

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// Clock lowering — rtc_set_time / rtc_get_time on the `rtc` DT alias
+//
+// The alias is Zephyr's own discovery convention. Boards with a hardware
+// calendar RTC alias it themselves; the overlay generator synthesizes a
+// zephyr,rtc-counter shim (a child of the board's first free counter — the
+// counter driver keeps the parent, so Counter and Clock coexist) when they
+// do not.
+//
+// Epoch ↔ civil conversion is Howard Hinnant's days_from_civil pair —
+// pure int64 arithmetic, no libc timezone machinery, valid over the whole
+// Unix range. The helpers live in the shim block so both ops share them.
+// ----------------------------------------------------------------------------
+const RTC_DEV = 'DEVICE_DT_GET(DT_ALIAS(rtc))';
+/** The conversion helpers + device handle. Called from shimLines when the
+ *  program uses clock.* — each helper only when its consuming op appears
+ *  (a now()-only program must not carry the unused set() helper: -Werror
+ *  fails the build on unreferenced static functions). */
+export function clockInitLines(usage) {
+    const lines = [
+        '// CUTTLEFISH_CLOCK_BEGIN',
+        `static const struct device* __tc_rtc = ${RTC_DEV};`,
+    ];
+    if (usage.now) {
+        lines.push('static int64_t __tc_days_from_civil(int32_t yy, int32_t mm, int32_t dd) {', '    yy -= (mm <= 2) ? 1 : 0;', '    const int32_t era = (yy >= 0 ? yy : yy - 399) / 400;', '    const int32_t yoe = yy - era * 400;', '    const int32_t doy = (153 * (mm + (mm > 2 ? -3 : 9)) + 2) / 5 + dd - 1;', '    const int32_t doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;', '    return (static_cast<int64_t>(era) * 146097) + static_cast<int64_t>(doe) - 719468;', '}');
+    }
+    if (usage.set) {
+        lines.push('static void __tc_civil_from_days(int64_t z, int32_t* yy, int32_t* mm, int32_t* dd) {', '    z += 719468;', '    const int64_t era = (z >= 0 ? z : z - 146096) / 146097;', '    const int64_t doe = z - (era * 146097);', '    const int64_t yoe = (doe - (doe / 1460) + (doe / 36524) - (doe / 146096)) / 365;', '    const int64_t y = yoe + (era * 400);', '    const int64_t doy = doe - ((365 * yoe) + (yoe / 4) - (yoe / 100));', '    const int64_t mp = ((5 * doy) + 2) / 153;', '    const int64_t d = doy - (((153 * mp) + 2) / 5) + 1;', '    const int64_t m = mp + (mp < 10 ? 3 : -9);', '    *yy = static_cast<int32_t>(y + (m <= 2 ? 1 : 0));', '    *mm = static_cast<int32_t>(m);', '    *dd = static_cast<int32_t>(d);', '}');
+    }
+    lines.push('// CUTTLEFISH_CLOCK_END');
+    return lines;
+}
+/** The all-zero/unknown rtc_time initializer (wday/yday unknown per the
+ * struct's contract). */
+const TM_INIT = 'struct rtc_time __tc_tm = { 0, 0, 0, 0, 0, 0, -1, -1, -1, 0 }';
+/**
+ * Resolve a HAL clock.* op to Zephyr C++.
+ * Returns `{ code }` for set, `{ expression }` for now.
+ */
+export function lowerClock(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'clock.set': {
+            // epoch (runtime text) → civil date → rtc_set_time.
+            return {
+                code: `{ int64_t __tc_ep = static_cast<int64_t>(${o.epoch}); int32_t __tc_y = 0; int32_t __tc_mo = 0; int32_t __tc_d = 0; __tc_civil_from_days(__tc_ep / 86400, &__tc_y, &__tc_mo, &__tc_d); int64_t __tc_sod = __tc_ep % 86400; ${TM_INIT}; __tc_tm.tm_year = __tc_y - 1900; __tc_tm.tm_mon = __tc_mo - 1; __tc_tm.tm_mday = __tc_d; __tc_tm.tm_hour = static_cast<int32_t>(__tc_sod / 3600); __tc_tm.tm_min = static_cast<int32_t>((__tc_sod % 3600) / 60); __tc_tm.tm_sec = static_cast<int32_t>(__tc_sod % 60); (void)rtc_set_time(__tc_rtc, &__tc_tm); }`,
+            };
+        }
+        case 'clock.now': {
+            return {
+                expression: `({ ${TM_INIT}; double __tc_epoch = 0.0; if (rtc_get_time(__tc_rtc, &__tc_tm) == 0) { int64_t __tc_days = __tc_days_from_civil(__tc_tm.tm_year + 1900, __tc_tm.tm_mon + 1, __tc_tm.tm_mday); __tc_epoch = static_cast<double>((__tc_days * 86400) + (static_cast<int64_t>(__tc_tm.tm_hour) * 3600) + (static_cast<int64_t>(__tc_tm.tm_min) * 60) + static_cast<int64_t>(__tc_tm.tm_sec)); } __tc_epoch; })`,
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/hid.d.ts

@@ -0,0 +1,27 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/** Modifier tokens — a separate bitmask enum in Zephyr (usage codes start
+ *  at 4, which collides with modifier bits, so the two kinds CANNOT share
+ *  one runtime branch: the lowering emits different code per kind).
+ *  Exported for the hid.h drift-guard test (every mapped macro must exist
+ *  in Zephyr's header). */
+export declare const KEY_MODIFIER_TOKENS: Record<string, string>;
+/** Is this KEY.* token a modifier (bitmask) rather than a usage code? */
+export declare function isHidModifierToken(token: string): boolean;
+/** Map a KEY or MOUSE token (or pass a runtime expression through) to C. */
+export declare function hidTokenToMacro(token: string, kind: 'key' | 'button'): string;
+/**
+ * Emit the HID interface state for one protocol. Called from shimLines when
+ * the program uses hid.* — one device handle, one report buffer, the boot
+ * report descriptor, and the guarded register helper that also starts the
+ * shared usbd context (the same one CDC rides).
+ */
+export declare function hidInitLines(protocol: 'keyboard' | 'mouse'): string[];
+/**
+ * Resolve a HAL hid.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerHid(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};