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

package/src/framework.manifest.ts

@@ -104,6 +104,91 @@ 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',
       },
     },
 
@@ -150,6 +235,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: {
@@ -286,11 +377,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',
@@ -403,10 +508,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,
@@ -533,6 +641,19 @@ export default defineFrameworkManifest({
   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/src/index.ts

@@ -26,9 +26,19 @@ 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 {

package/src/licenses.ts

@@ -37,6 +37,7 @@ import {
 } from '@typecad/cuttlefish/api/shared';
 import { discoverWest } from './toolchain/west-discover.js';
 import { westSpawn } from './toolchain/west-spawn.js';
+import { filterLinkedModules, findCompileCommandsPath } from './west-inventory.js';
 
 // ---------------------------------------------------------------------------
 // Outcome + runner types
@@ -72,40 +73,6 @@ export interface ZephyrLicensesRunner {
   readdir: ReadDir;
 }
 
-// ---------------------------------------------------------------------------
-// Linked-module filtering (project scope)
-// ---------------------------------------------------------------------------
-
-/** Normalize a path for case-insensitive, separator-agnostic comparison. */
-function norm(p: string): string {
-  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: string,
-  modules: { name: string; abspath: string }[],
-): { name: string; abspath: string }[] {
-  let arr: unknown;
-  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 as { file?: unknown })?.file === 'string' ? (e as { file: string }).file : ''))
-    .join('\n');
-  return modules.filter((m) => blob.includes(norm(m.abspath) + '/'));
-}
-
 // ---------------------------------------------------------------------------
 // scanZephyrLicenses — enumerate + resolve the workspace dependency set
 // ---------------------------------------------------------------------------
@@ -205,55 +172,6 @@ export function scanZephyrLicenses(
 // 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: ReadFile, readdir: ReadDir): string | null {
-  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: string) => {
-    const n = norm(p);
-    return n.endsWith('/build/compile_commands.json') || n.endsWith('\\build\\compile_commands.json');
-  };
-  let found: string | undefined;
-  const seen = new Set<string>();
-  const walk = (dir: string, depth: number): void => {
-    if (found || depth > 4 || seen.has(dir)) return;
-    seen.add(dir);
-    let entries: string[];
-    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(): ZephyrLicensesRunner | null {
   const install = discoverWest();
   if (!install) return null;
@@ -315,7 +233,10 @@ function defaultRunner(): ZephyrLicensesRunner | null {
     topdir,
     listModules,
     zephyrBase,
-    compileCommands: () => findCompileCommandsText(readFile, readdir),
+    compileCommands: () => {
+      const p = findCompileCommandsPath(readFile, readdir);
+      return p ? (readFile(p) ?? null) : null;
+    },
     readFile,
     readdir,
   };

package/src/lowering/can.ts

@@ -0,0 +1,140 @@
+// ---------------------------------------------------------------------------
+// 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).
+// ----------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+
+/** The C variable names for a CAN controller's state. */
+function prefix(idx: number): string {
+  return `__tc_can${idx}`;
+}
+
+/** 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 function canInitLines(chip: ZephyrChipDescriptor, controllerIndex: number, usage: CanUsage): string[] {
+  const ctrl = chip.can?.controllers[controllerIndex];
+  if (!ctrl) return [];
+  const p = prefix(controllerIndex);
+  const lines: string[] = [
+    '// 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: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  // 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 ?? []) as (number | string)[];
+      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/src/lowering/clock.ts

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ----------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+
+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: { set: boolean; now: boolean }): string[] {
+  const lines: string[] = [
+    '// 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: HALOpIR): { code?: string; expression?: string } {
+  const o = op as any;
+
+  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.`,
+      );
+  }
+}