driverge-mcp 0.0.0 → 0.0.1

package/dist/codegen/portable.js

@@ -1,15 +1,31 @@
 // Portable thin-HAL codegen. Renders a deterministic C driver skeleton from the
 // frozen DatasheetJson: register/command constants, bit-field mask+shift macros,
-// the 5-function thin-HAL seam (and NOTHING platform-specific — see
-// thin-hal-non-negotiable), function stubs, and TODO(driverge) markers at every
-// spot needing host-AI reasoning. Output is reproducible: no timestamps, stable
-// ordering. The host AI fills the brief and re-validates via validate_driver.
-import { HEX_ONLY, fieldMask, hex2, macro, slug } from "./ident.js";
-const AUTOGEN = (part, mfr, busLine) => [
+// the per-bus thin-HAL seam (I2C: hal_i2c_read/write + hal_delay_ms; SPI: one
+// combined hal_spi_transfer + hal_delay_ms — see BUS_SEAM below and
+// thin-hal-non-negotiable) and NOTHING platform-specific, function stubs, and
+// TODO(driverge) markers at every spot needing host-AI reasoning. Output is
+// reproducible: no timestamps, stable ordering. The host AI fills the brief and
+// re-validates via validate_driver.
+import { registerWidth } from "../pdf/types.js";
+import { HEX_ONLY, commentSafe, fieldMask, macro, maskHex, slug } from "./ident.js";
+// Exported: the "cpp" language flavor (see portable-cpp.ts) renders the SAME
+// #define macro / TODO blocks and thin-HAL seam declarations as this C
+// generator — reusing these pure helpers instead of re-deriving them is how the
+// two flavors stay byte-for-byte consistent on everything except the
+// struct-vs-class/free-function-vs-method shape (see Session D: cpp language
+// option).
+// part/mfr/busLine are free text lifted verbatim from the parsed datasheet
+// (metadata.part/manufacturer; busLine's only free-text ingredient is the I2C
+// address, which is hex-validated, but commentSafe-ing the whole trio here —
+// once, in the one place every AUTOGEN caller shares — is simpler and safer
+// than re-deriving which piece is "safe enough" at each call site) — see B2:
+// comment-escape injection. commentSafe neutralizes any embedded `*/`/`/*` so
+// none of the three can ever prematurely close (or spoof) this block comment.
+export const AUTOGEN = (part, mfr, busLine) => [
     "/*",
-    ` * ${part} driver — portable thin-HAL skeleton (generated by Driverge).`,
-    ` * Manufacturer: ${mfr}`,
-    ` * ${busLine}`,
+    ` * ${commentSafe(part)} driver — portable thin-HAL skeleton (generated by Driverge).`,
+    ` * Manufacturer: ${commentSafe(mfr)}`,
+    ` * ${commentSafe(busLine)}`,
     " *",
     " * This is a deterministic skeleton. Every TODO(driverge) marks a spot the",
     " * host AI must complete (init sequence, vendor quirks, docs) using the",
@@ -22,7 +38,7 @@ const AUTOGEN = (part, mfr, busLine) => [
 // ---------------------------------------------------------------------------
 // register_map
 // ---------------------------------------------------------------------------
-function registerConstants(prefix, registers) {
+export function registerConstants(prefix, registers) {
     const lines = ["/* Register addresses. */"];
     const seen = new Set();
     for (const r of registers) {
@@ -36,28 +52,178 @@ function registerConstants(prefix, registers) {
     }
     return lines;
 }
-function bitFieldMacros(prefix, registers) {
+/** Where the host AI must enumerate a register map that Driverge couldn't extract. */
+export function registerMapTodo(prefix, pages) {
+    const where = pages.length
+        ? ` (register section detected on page(s) ${pages.join(", ")})`
+        : "";
+    return [
+        "/* Register map. */",
+        "/* TODO(driverge): Driverge could not auto-extract this device's register map",
+        ` * from the datasheet${where}. Enumerate the registers from the datasheet (read`,
+        " * the driverge://datasheet resource) and add one line per register:",
+        ` *     #define ${prefix}_REG_<NAME> 0x..`,
+        ` * plus ${prefix}_<REG>_<FIELD>_MASK / _SHIFT macros for any bit fields. */`,
+    ];
+}
+/** Where the host AI must enumerate a command set that Driverge couldn't extract. */
+export function commandSetTodo(prefix, pages) {
+    const where = pages.length
+        ? ` (command section detected on page(s) ${pages.join(", ")})`
+        : "";
+    return [
+        "/* Command codes. */",
+        "/* TODO(driverge): Driverge could not auto-extract this device's command set",
+        ` * from the datasheet${where}. Enumerate the commands from the datasheet (read`,
+        " * the driverge://datasheet resource) and add one line per command:",
+        ` *     #define ${prefix}_CMD_<NAME> 0x.. */`,
+    ];
+}
+/** fill_in_brief.register_map_todo text — shared by the C and cpp generators. */
+export function registerMapTodoText(json, name, prefix) {
+    return `Enumerate ${json.metadata.part || name}'s register map from the datasheet — Driverge could not auto-extract it. Add a "#define ${prefix}_REG_<NAME> 0x.." for each register address (and ${prefix}_<REG>_<FIELD>_MASK/_SHIFT for bit fields) using the driverge://datasheet resource, then wire the read/write helpers accordingly.`;
+}
+/** fill_in_brief.command_set_todo text — shared by the C and cpp generators. */
+export function commandSetTodoText(json, name, prefix) {
+    return `Enumerate ${json.metadata.part || name}'s command set from the datasheet — Driverge could not auto-extract it. Add a "#define ${prefix}_CMD_<NAME> 0x.." for each command using the driverge://datasheet resource.`;
+}
+export const BUS_SEAM = {
+    I2C: {
+        decl: [
+            "void hal_i2c_write(uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);",
+            "void hal_i2c_read (uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);",
+        ],
+        handleField: "    uint8_t i2c_addr;",
+        readBody: ["    hal_i2c_read(dev->i2c_addr, reg, value, 1);"],
+        writeBody: ["    hal_i2c_write(dev->i2c_addr, reg, &value, 1);"],
+    },
+    SPI: {
+        decl: [
+            "/* One call = one CS-framed transaction: CS is asserted, tx_len bytes are",
+            " * clocked out, then rx_len bytes are clocked in, then CS is deasserted.",
+            " * tx/rx may be NULL when their respective length is 0. CS is handled",
+            " * entirely inside hal_spi_transfer — callers never touch it. */",
+            "void hal_spi_transfer(const uint8_t *tx, uint16_t tx_len, uint8_t *rx, uint16_t rx_len);",
+        ],
+        handleField: "    uint8_t _reserved; /* platform CS handled in hal_spi_transfer */",
+        readBody: ["    hal_spi_transfer(&reg, 1, value, 1);"],
+        writeBody: [
+            "    uint8_t frame[2];",
+            "    frame[0] = reg;",
+            "    frame[1] = value;",
+            "    hal_spi_transfer(frame, 2, NULL, 0);",
+        ],
+    },
+    UART: {
+        decl: [
+            "/* hal_uart_write is a blocking write of len bytes. */",
+            "/* hal_uart_read reads up to len bytes and returns the count actually read",
+            " * within timeout_ms. */",
+            "void hal_uart_write(const uint8_t *data, uint16_t len);",
+            "uint16_t hal_uart_read(uint8_t *data, uint16_t len, uint32_t timeout_ms);",
+        ],
+        handleField: "    uint8_t _reserved; /* platform UART handle is bound inside the hal_uart_* implementation */",
+        readBody: [],
+        writeBody: [],
+    },
+    // Session C — CAN. Unlike I2C's two-function read/write pair or SPI's single
+    // transfer, one hal_can_transfer() call both sends a frame AND (optionally)
+    // waits for the one response frame it provokes — CAN has no separate
+    // read/write primitive, only "put a frame on the bus, addressed by
+    // arbitration id, and maybe get one back". rx_len is in/out (capacity in,
+    // actual byte count out) because a CAN payload is 0-8 bytes, not a fixed
+    // size.
+    CAN: {
+        decl: [
+            "/* A call sends one CAN frame to arbitration id `id` and optionally waits",
+            " * for one response frame (pass rx/rx_len NULL/0 to only transmit).",
+            " * Returns 0 on success. rx_len is in/out: in = buffer capacity, out =",
+            " * bytes actually received. */",
+            "int hal_can_transfer(uint32_t id, const uint8_t *tx, uint8_t tx_len, uint8_t *rx, uint8_t *rx_len, uint32_t timeout_ms);",
+        ],
+        handleField: "    uint8_t _reserved; /* platform CAN peripheral/arbitration-id binding is handled inside the hal_can_transfer implementation */",
+        readBody: [],
+        writeBody: [],
+    },
+};
+/** Which BUS_SEAM row a protocol.bus resolves to. "unknown" defaults to the I2C
+ *  seam, matching the pre-existing (pre-Session-B) fallback behavior. */
+export function seamBusFor(bus) {
+    if (bus === "SPI")
+        return "SPI";
+    if (bus === "UART")
+        return "UART";
+    if (bus === "CAN")
+        return "CAN";
+    return "I2C";
+}
+// UART and CAN have no universal register/command framing (start bytes, IDs,
+// checksums, arbitration ids are all device-specific — see decisions:
+// thin-hal-non-negotiable), so rather than fabricate a wire format, the
+// generated body is a deliberate TODO(driverge) reasoning gap over the raw
+// seam call(s): a compilable placeholder (params voided, returns -1) that
+// names the seam function(s) so the host AI knows exactly what to build on
+// top of. See fill_in_brief.framing_todo.
+export function uartFramingBody(params) {
+    return [
+        "    /* TODO(driverge): this device has no universal UART register/command",
+        "     * framing — build the request frame and call hal_uart_write(), then",
+        "     * parse the response via hal_uart_read(). See fill_in_brief.framing_todo. */",
+        ...params.map((p) => `    (void)${p};`),
+        "    return -1;",
+    ];
+}
+export function canFramingBody(params) {
+    return [
+        "    /* TODO(driverge): this device has no universal CAN register/command",
+        "     * framing — build the CAN frame and call hal_can_transfer() with this",
+        "     * part's arbitration id to send it (and receive any response). See",
+        "     * fill_in_brief.framing_todo. */",
+        ...params.map((p) => `    (void)${p};`),
+        "    return -1;",
+    ];
+}
+// CAN-specific reasoning gap shared by both interface kinds: which arbitration
+// id / SDO index / message ID maps to which register or command is
+// device-specific and belongs in fill_in_brief.quirks_todo, NOT a generic
+// checksum note reused from UART.
+export const CAN_QUIRKS_NOTE = "Confirm the arbitration IDs / SDO message schema this part uses for register/command access from the datasheet; CAN device interfaces are device-specific.";
+export function bitFieldMacros(prefix, registers) {
     const lines = [];
     for (const r of registers) {
         if (r.bitFields.length === 0)
             continue;
-        lines.push("", `/* ${r.name} bit fields. */`);
+        const width = registerWidth(r);
+        const widthNote = width > 8 ? ` (${width}-bit register)` : "";
+        // r.name is free text lifted verbatim from the parsed datasheet — see B2:
+        // comment-escape injection — so it must not be allowed to close this
+        // block comment early via an embedded `*/`.
+        lines.push("", `/* ${commentSafe(r.name)} bit fields${widthNote}. */`);
         for (const f of r.bitFields) {
             const base = `${prefix}_${macro(r.name)}_${macro(f.name)}`;
-            lines.push(`#define ${base}_MASK  ${hex2(fieldMask(f.msb, f.lsb))}`);
+            lines.push(`#define ${base}_MASK  ${maskHex(fieldMask(f.msb, f.lsb, width), width)}`);
             lines.push(`#define ${base}_SHIFT ${f.lsb}`);
         }
     }
     return lines;
 }
-function registerDriver(json, name, prefix) {
-    const registers = json.interface.registers;
-    const spi = json.protocol.bus === "SPI";
+function registerDriver(json, registers, name, prefix) {
+    const busKind = seamBusFor(json.protocol.bus);
+    const spi = busKind === "SPI";
+    const uart = busKind === "UART";
+    const can = busKind === "CAN";
+    const seam = BUS_SEAM[busKind];
     const addr = json.protocol.addresses?.[0];
     const guard = `${prefix}_H`;
     const type = `${name}_t`;
     const header = [
-        AUTOGEN(json.metadata.part || name, json.metadata.manufacturer, spi ? "Bus: SPI" : `Bus: I2C, address ${addr ?? "(unknown — see TODO)"}`),
+        AUTOGEN(json.metadata.part || name, json.metadata.manufacturer, spi
+            ? "Bus: SPI"
+            : uart
+                ? "Bus: UART"
+                : can
+                    ? "Bus: CAN"
+                    : `Bus: I2C, address ${addr ?? "(unknown — see TODO)"}`),
         "",
         `#ifndef ${guard}`,
         `#define ${guard}`,
@@ -70,7 +236,7 @@ function registerDriver(json, name, prefix) {
         "#endif",
         "",
     ];
-    if (!spi) {
+    if (!spi && !uart && !can) {
         if (addr) {
             header.push("/* I2C device address. */", `#define ${prefix}_I2C_ADDR ${addr}`, "");
         }
@@ -78,25 +244,28 @@ function registerDriver(json, name, prefix) {
             header.push("/* TODO(driverge): set the I2C device address (not found in the datasheet parse). */", `#define ${prefix}_I2C_ADDR 0x00`, "");
         }
     }
-    header.push(...registerConstants(prefix, registers));
+    const regLines = registerConstants(prefix, registers);
+    const hasRegs = regLines.some((l) => l.startsWith("#define"));
+    header.push(...(hasRegs
+        ? regLines
+        : registerMapTodo(prefix, json.extraction?.detectedPages ?? [])));
+    if (registers.some((r) => registerWidth(r) > 8)) {
+        header.push("", "/* NOTE: some registers here are wider than 8 bits (see the per-register", " * annotations). Bit-field masks are register-width correct; multi-byte access", " * framing (byte order / transfer size) is device-specific and belongs on the", " * hal_* seam. */");
+    }
     const bits = bitFieldMacros(prefix, registers);
     if (bits.length > 0)
         header.push("", "/* Bit-field mask/shift accessors. */", ...bits);
-    header.push("", "/* Thin-HAL seam — implement these for your platform (see thin-hal). */", ...(spi
-        ? [
-            "void hal_spi_write(uint8_t *data, uint16_t len);",
-            "void hal_spi_read (uint8_t *data, uint16_t len);",
-        ]
-        : [
-            "void hal_i2c_write(uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);",
-            "void hal_i2c_read (uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);",
-        ]), "void hal_delay_ms (uint32_t ms);", "", "/* Driver handle. */", `typedef struct {`, spi ? "    uint8_t _reserved; /* platform CS handled in hal_spi_* */" : "    uint8_t i2c_addr;", `} ${type};`, "", "/* Public API. */", `int ${name}_init(${type} *dev);`, `int ${name}_read_register(${type} *dev, uint8_t reg, uint8_t *value);`, `int ${name}_write_register(${type} *dev, uint8_t reg, uint8_t value);`, "", '#ifdef __cplusplus', "}", "#endif", `#endif /* ${guard} */`, "");
-    const readBody = spi
-        ? ["    hal_spi_write(&reg, 1);", "    hal_spi_read(value, 1);"]
-        : ["    hal_i2c_read(dev->i2c_addr, reg, value, 1);"];
-    const writeBody = spi
-        ? ["    uint8_t frame[2];", "    frame[0] = reg;", "    frame[1] = value;", "    hal_spi_write(frame, 2);"]
-        : ["    hal_i2c_write(dev->i2c_addr, reg, &value, 1);"];
+    header.push("", "/* Thin-HAL seam — implement these for your platform (see thin-hal). */", ...seam.decl, "void hal_delay_ms (uint32_t ms);", "", "/* Driver handle. */", `typedef struct {`, seam.handleField, `} ${type};`, "", "/* Public API. */", `int ${name}_init(${type} *dev);`, `int ${name}_read_register(${type} *dev, uint8_t reg, uint8_t *value);`, `int ${name}_write_register(${type} *dev, uint8_t reg, uint8_t value);`, "", '#ifdef __cplusplus', "}", "#endif", `#endif /* ${guard} */`, "");
+    const readBody = uart
+        ? uartFramingBody(["dev", "reg", "value"])
+        : can
+            ? canFramingBody(["dev", "reg", "value"])
+            : ["    if (dev == NULL || value == NULL) {", "        return -1;", "    }", ...seam.readBody, "    return 0;"];
+    const writeBody = uart
+        ? uartFramingBody(["dev", "reg", "value"])
+        : can
+            ? canFramingBody(["dev", "reg", "value"])
+            : ["    if (dev == NULL) {", "        return -1;", "    }", ...seam.writeBody, "    return 0;"];
     const source = [
         `#include "${name}.h"`,
         "",
@@ -104,55 +273,79 @@ function registerDriver(json, name, prefix) {
         "    if (dev == NULL) {",
         "        return -1;",
         "    }",
-        ...(spi ? [] : [`    dev->i2c_addr = ${prefix}_I2C_ADDR;`]),
-        "    /* TODO(driverge): implement the power-on / reset init sequence — the",
-        "     * correct register write order and values, plus any required startup",
-        `     * delay. See fill_in_brief.init_sequence_todo. Use ${name}_write_register()`,
-        "     * and hal_delay_ms(). */",
+        ...(spi || uart || can ? [] : [`    dev->i2c_addr = ${prefix}_I2C_ADDR;`]),
+        ...registerInitTodo(uart, can, `${name}_write_register()`),
         "    return 0;",
         "}",
         "",
         `int ${name}_read_register(${type} *dev, uint8_t reg, uint8_t *value) {`,
-        "    if (dev == NULL || value == NULL) {",
-        "        return -1;",
-        "    }",
         ...readBody,
-        "    return 0;",
         "}",
         "",
         `int ${name}_write_register(${type} *dev, uint8_t reg, uint8_t value) {`,
-        "    if (dev == NULL) {",
-        "        return -1;",
-        "    }",
         ...writeBody,
-        "    return 0;",
         "}",
         "",
     ];
+    const brief = registerBrief(json);
+    if (!hasRegs) {
+        brief.register_map_todo = registerMapTodoText(json, name, prefix);
+    }
     return {
         files: makeFiles(name, header, source),
-        fill_in_brief: registerBrief(json),
+        fill_in_brief: brief,
     };
 }
-function registerBrief(json) {
+export function registerBrief(json, calls) {
     const part = json.metadata.part || "the device";
-    return {
+    const name = slug(part);
+    const c = {
+        init: calls?.init ?? `${name}_init`,
+        readRegister: calls?.readRegister ?? "read_register",
+        writeRegister: calls?.writeRegister ?? "write_register",
+    };
+    const quirks = [
+        `Capture vendor timing/behavior quirks for ${part} (e.g. mandatory power-on delay, soft-reset requirement, read-back constraints) and enforce them in ${c.init} using hal_delay_ms.`,
+    ];
+    if (json.protocol.bus === "SPI") {
+        quirks.push(`Verify the register address bit convention: many SPI chips set the address MSB for reads (e.g. 0x80 | reg) — check the datasheet's SPI framing and adjust ${c.readRegister}/${c.writeRegister}.`);
+    }
+    if (json.protocol.bus === "UART") {
+        quirks.push("Verify the response checksum algorithm from the datasheet before trusting frame data — vendor checksum/CRC methods for UART command-and-response parts vary.");
+    }
+    if (json.protocol.bus === "CAN") {
+        quirks.push(CAN_QUIRKS_NOTE);
+    }
+    const brief = {
         init_sequence_todo: `Determine the correct power-on/reset init sequence for ${part}: which registers to write, in what order, with what values (mode/config), and any required startup delay. Read the datasheet init/operation section via the driverge://datasheet resource.`,
-        quirks_todo: `Capture vendor timing/behavior quirks for ${part} (e.g. mandatory power-on delay, soft-reset requirement, read-back constraints) and enforce them in ${slug(part)}_init using hal_delay_ms.`,
+        quirks_todo: quirks.join(" "),
         doc_todo: "Add Doxygen comments for all public functions and any device-specific compensation/conversion formulas.",
     };
+    if (json.protocol.bus === "UART") {
+        brief.framing_todo = `Implement ${name}'s UART frame protocol in ${c.readRegister}/${c.writeRegister}: build request frames with hal_uart_write and parse responses with hal_uart_read, per the datasheet's communication/frame-format section.`;
+    }
+    if (json.protocol.bus === "CAN") {
+        brief.framing_todo = `Implement ${name}'s CAN frame protocol in ${c.readRegister}/${c.writeRegister}: build request frames and call hal_can_transfer() with this part's arbitration id(s), per the datasheet's CAN communication/message-ID section.`;
+    }
+    return brief;
 }
 // ---------------------------------------------------------------------------
 // command_set
 // ---------------------------------------------------------------------------
-function commandDriver(json, name, prefix) {
-    const commands = json.interface.commands;
+function commandDriver(json, commands, name, prefix) {
+    const uart = json.protocol.bus === "UART";
+    const can = json.protocol.bus === "CAN";
+    const noAddrBus = uart || can; // neither UART nor CAN has a bus device address
     const addr = json.protocol.addresses?.[0];
     const crc = commands.find((c) => c.crc)?.crc;
     const guard = `${prefix}_H`;
     const type = `${name}_t`;
     const header = [
-        AUTOGEN(json.metadata.part || name, json.metadata.manufacturer, `Bus: I2C, address ${addr ?? "(unknown — see TODO)"} · command-set device`),
+        AUTOGEN(json.metadata.part || name, json.metadata.manufacturer, uart
+            ? "Bus: UART · command-set device"
+            : can
+                ? "Bus: CAN · command-set device"
+                : `Bus: I2C, address ${addr ?? "(unknown — see TODO)"} · command-set device`),
         "",
         `#ifndef ${guard}`,
         `#define ${guard}`,
@@ -165,25 +358,48 @@ function commandDriver(json, name, prefix) {
         "#endif",
         "",
     ];
-    if (addr) {
+    if (noAddrBus) {
+        // No bus device address on UART/CAN — only I2C command-set parts get an
+        // *_I2C_ADDR macro (see fill_in_brief.framing_todo for the UART/CAN
+        // reasoning gap this leaves instead).
+    }
+    else if (addr) {
         header.push("/* I2C device address. */", `#define ${prefix}_I2C_ADDR ${addr}`, "");
     }
     else {
         header.push("/* TODO(driverge): set the I2C device address. */", `#define ${prefix}_I2C_ADDR 0x00`, "");
     }
-    header.push("/* Command codes. */");
-    const seen = new Set();
-    for (const c of commands) {
-        const macroName = `${prefix}_CMD_${macro(c.name)}`;
-        if (seen.has(macroName))
-            continue;
-        seen.add(macroName);
-        header.push(`#define ${macroName} ${c.code.toUpperCase().replace("0X", "0x")}`);
+    if (commands.length === 0) {
+        header.push(...commandSetTodo(prefix, json.extraction?.detectedPages ?? []));
+    }
+    else {
+        header.push("/* Command codes. */");
+        const seen = new Set();
+        for (const c of commands) {
+            const macroName = `${prefix}_CMD_${macro(c.name)}`;
+            if (seen.has(macroName))
+                continue;
+            seen.add(macroName);
+            const line = `#define ${macroName} ${c.code.toUpperCase().replace("0X", "0x")}`;
+            // c.params is currently always hex-derived (prose-commands.ts) and thus
+            // safe as-is, but the Command type doesn't guarantee that — commentSafe
+            // defensively, same reasoning as AUTOGEN/bitFieldMacros above (B2).
+            header.push(c.params && c.params.length > 0
+                ? `${line}  /* params: ${commentSafe(c.params.join(", "))} */`
+                : line);
+        }
     }
     if (crc) {
         header.push("", `/* CRC-${crc.width} checksum parameters. */`, `#define ${prefix}_CRC_POLY ${crc.poly}`, `#define ${prefix}_CRC_INIT ${crc.init}`);
     }
-    header.push("", "/* Thin-HAL seam — implement these for your platform (see thin-hal). */", "void hal_i2c_write(uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);", "void hal_i2c_read (uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);", "void hal_delay_ms (uint32_t ms);", "", "/* Driver handle. */", "typedef struct {", "    uint8_t i2c_addr;", `} ${type};`, "", "/* Public API. */", `int ${name}_init(${type} *dev);`, `int ${name}_send_command(${type} *dev, uint16_t command);`, `int ${name}_read_data(${type} *dev, uint8_t *buffer, uint16_t len);`, ...(crc ? [`uint8_t ${name}_crc8(const uint8_t *data, uint16_t len);`] : []), "", '#ifdef __cplusplus', "}", "#endif", `#endif /* ${guard} */`, "");
+    header.push("", "/* Thin-HAL seam — implement these for your platform (see thin-hal). */", ...(uart
+        ? BUS_SEAM.UART.decl
+        : can
+            ? BUS_SEAM.CAN.decl
+            : [
+                "void hal_i2c_write(uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);",
+                "void hal_i2c_read (uint8_t addr, uint8_t reg, uint8_t *data, uint16_t len);",
+            ]), "void hal_delay_ms (uint32_t ms);", "", "/* Driver handle. */", "typedef struct {", uart ? BUS_SEAM.UART.handleField : can ? BUS_SEAM.CAN.handleField : "    uint8_t i2c_addr;", `} ${type};`, "", "/* Public API. */", `int ${name}_init(${type} *dev);`, `int ${name}_send_command(${type} *dev, uint16_t command);`, `int ${name}_read_data(${type} *dev, uint8_t *buffer, uint16_t len);`, ...(crc ? [`uint8_t ${name}_crc8(const uint8_t *data, uint16_t len);`] : []), "", '#ifdef __cplusplus', "}", "#endif", `#endif /* ${guard} */`, "");
     const source = [
         `#include "${name}.h"`,
         "",
@@ -191,68 +407,172 @@ function commandDriver(json, name, prefix) {
         "    if (dev == NULL) {",
         "        return -1;",
         "    }",
-        `    dev->i2c_addr = ${prefix}_I2C_ADDR;`,
-        "    /* TODO(driverge): power-up / soft-reset sequence and startup delay. See",
-        "     * fill_in_brief.init_sequence_todo. */",
+        ...(noAddrBus ? [] : [`    dev->i2c_addr = ${prefix}_I2C_ADDR;`]),
+        ...COMMAND_INIT_TODO,
         "    return 0;",
         "}",
         "",
         `int ${name}_send_command(${type} *dev, uint16_t command) {`,
-        "    uint8_t msb;",
-        "    uint8_t lsb;",
-        "    if (dev == NULL) {",
-        "        return -1;",
-        "    }",
-        "    msb = (uint8_t)(command >> 8);",
-        "    lsb = (uint8_t)(command & 0xFF);",
-        "    /* Command frame = [MSB][LSB]. hal_i2c_write emits the reg byte then the",
-        "     * data bytes, so MSB-as-reg + LSB-as-data yields the correct 2-byte frame. */",
-        "    hal_i2c_write(dev->i2c_addr, msb, &lsb, 1);",
-        "    return 0;",
+        ...(uart
+            ? uartFramingBody(["dev", "command"])
+            : can
+                ? canFramingBody(["dev", "command"])
+                : [
+                    "    uint8_t msb;",
+                    "    uint8_t lsb;",
+                    "    if (dev == NULL) {",
+                    "        return -1;",
+                    "    }",
+                    "    msb = (uint8_t)(command >> 8);",
+                    "    lsb = (uint8_t)(command & 0xFF);",
+                    ...I2C_COMMAND_FRAME_NOTE,
+                    "    hal_i2c_write(dev->i2c_addr, msb, &lsb, 1);",
+                    "    return 0;",
+                ]),
         "}",
         "",
         `int ${name}_read_data(${type} *dev, uint8_t *buffer, uint16_t len) {`,
-        "    if (dev == NULL || buffer == NULL) {",
-        "        return -1;",
-        "    }",
-        "    /* TODO(driverge): read `len` response bytes (data words each followed by a",
-        "     * CRC byte). Most command-set parts use a plain I2C read with no pointer",
-        "     * byte — adapt the HAL call to your platform, then check each word with",
-        `     * ${name}_crc8(). See fill_in_brief.quirks_todo. */`,
-        "    (void)dev;",
-        "    (void)buffer;",
-        "    (void)len;",
-        "    return 0;",
+        ...(uart
+            ? uartFramingBody(["dev", "buffer", "len"])
+            : can
+                ? canFramingBody(["dev", "buffer", "len"])
+                : [
+                    "    if (dev == NULL || buffer == NULL) {",
+                    "        return -1;",
+                    "    }",
+                    ...commandReadDataTodo(`${name}_crc8`),
+                    "    (void)dev;",
+                    "    (void)buffer;",
+                    "    (void)len;",
+                    "    return 0;",
+                ]),
         "}",
         "",
     ];
     if (crc) {
-        source.push(`uint8_t ${name}_crc8(const uint8_t *data, uint16_t len) {`, "    (void)data;", "    (void)len;", `    /* TODO(driverge): implement CRC-${crc.width} (poly ${prefix}_CRC_POLY, init`, `     * ${prefix}_CRC_INIT) per the datasheet checksum section. See`, "     * fill_in_brief.crc_todo. */", "    return 0;", "}", "");
+        source.push(...crc8Body(`${name}_crc8`, crc, prefix));
     }
+    const brief = commandBrief(json, commands, crc, uart, can, name, prefix);
+    return { files: makeFiles(name, header, source), fill_in_brief: brief };
+}
+export function commandBrief(json, commands, crc, uart, can, name, prefix, calls) {
+    const c = {
+        sendCommand: calls?.sendCommand ?? `${name}_send_command`,
+        readData: calls?.readData ?? `${name}_read_data`,
+        crc8: calls?.crc8 ?? `${name}_crc8`,
+    };
     const brief = {
         init_sequence_todo: `Determine the power-up / soft-reset sequence and any startup delay for ${json.metadata.part || "the device"}.`,
-        quirks_todo: `Implement ${name}_read_data for this part's actual read framing (clock stretching vs. fixed delay, number of data+CRC words per command) using the driverge://datasheet resource.`,
+        quirks_todo: uart
+            ? `Verify the response checksum algorithm from the datasheet before trusting ${c.readData}'s output — vendor checksum/CRC methods vary by part.`
+            : can
+                ? CAN_QUIRKS_NOTE
+                : `Implement ${c.readData} for this part's actual read framing (clock stretching vs. fixed delay, number of data+CRC words per command) using the driverge://datasheet resource.`,
         doc_todo: "Add Doxygen comments for all public functions and document each command's response layout.",
     };
     if (crc) {
-        brief.crc_todo = `Implement ${name}_crc8: CRC-${crc.width}, polynomial ${crc.poly}, init ${crc.init}, per the datasheet checksum section.`;
+        brief.crc_todo = `Implement ${c.crc8}: CRC-${crc.width}, polynomial ${crc.poly}, init ${crc.init}, per the datasheet checksum section.`;
     }
-    return { files: makeFiles(name, header, source), fill_in_brief: brief };
+    if (commands.length === 0) {
+        brief.command_set_todo = commandSetTodoText(json, name, prefix);
+    }
+    if (uart) {
+        brief.framing_todo = `Implement ${name}'s UART frame protocol in ${c.sendCommand}/${c.readData}: build request frames with hal_uart_write and parse responses with hal_uart_read, per the datasheet's communication/frame-format section.`;
+    }
+    if (can) {
+        brief.framing_todo = `Implement ${name}'s CAN frame protocol in ${c.sendCommand}/${c.readData}: build request frames and call hal_can_transfer() with this part's arbitration id(s), per the datasheet's CAN communication/message-ID section.`;
+    }
+    return brief;
 }
 // ---------------------------------------------------------------------------
-function makeFiles(name, header, source) {
+/**
+ * Static prose block shared by the C and cpp command_set init() bodies
+ * (mentions no function names, so there is nothing to parameterize).
+ */
+export const COMMAND_INIT_TODO = [
+    "    /* TODO(driverge): power-up / soft-reset sequence and startup delay. See",
+    "     * fill_in_brief.init_sequence_todo. */",
+];
+/** The I2C command-frame comment in send_command — no callable names, shared verbatim. */
+export const I2C_COMMAND_FRAME_NOTE = [
+    "    /* Command frame = [MSB][LSB]. hal_i2c_write emits the reg byte then the",
+    "     * data bytes, so MSB-as-reg + LSB-as-data yields the correct 2-byte frame. */",
+];
+/**
+ * read_data's "implement the actual read framing" TODO comment. `crc8Name` is
+ * the bare callable name (no parens) — `<name>_crc8` for C, `crc8` for cpp.
+ */
+export function commandReadDataTodo(crc8Name) {
+    return [
+        "    /* TODO(driverge): read `len` response bytes (data words each followed by a",
+        "     * CRC byte). Most command-set parts use a plain I2C read with no pointer",
+        "     * byte — adapt the HAL call to your platform, then check each word with",
+        `     * ${crc8Name}(). See fill_in_brief.quirks_todo. */`,
+    ];
+}
+/**
+ * Renders a CRC-8 stub function/method body. `qualifiedName` is the full
+ * callable name to emit — a free function (`sht3x_crc8`) for C or a qualified
+ * method (`Sht3x::crc8`) for cpp — so this single builder covers both without
+ * duplicating the TODO prose (Session D: cpp language option).
+ */
+export function crc8Body(qualifiedName, crc, prefix) {
+    return [
+        `uint8_t ${qualifiedName}(const uint8_t *data, uint16_t len) {`,
+        "    (void)data;",
+        "    (void)len;",
+        `    /* TODO(driverge): implement CRC-${crc.width} (poly ${prefix}_CRC_POLY, init`,
+        `     * ${prefix}_CRC_INIT) per the datasheet checksum section. See`,
+        "     * fill_in_brief.crc_todo. */",
+        "    return 0;",
+        "}",
+        "",
+    ];
+}
+/**
+ * register_map init()'s "implement the power-on/reset sequence" TODO comment.
+ * The uart/can branch mentions no callable names (just the seam functions), so
+ * it is identical for C and cpp; the register-access branch takes the write
+ * call as a parameter (`<name>_write_register()` for C, `writeRegister()` for
+ * cpp) so both flavors share this one builder (Session D: cpp language
+ * option).
+ */
+export function registerInitTodo(uart, can, writeRegisterCall) {
+    if (uart || can) {
+        return [
+            "    /* TODO(driverge): implement the power-on / reset init sequence — the",
+            "     * correct command/frame sequence and any required startup delay. See",
+            "     * fill_in_brief.init_sequence_todo and fill_in_brief.framing_todo. Use",
+            `     * ${uart ? "hal_uart_write()/hal_uart_read()" : "hal_can_transfer()"} and hal_delay_ms(). */`,
+        ];
+    }
+    return [
+        "    /* TODO(driverge): implement the power-on / reset init sequence — the",
+        "     * correct register write order and values, plus any required startup",
+        `     * delay. See fill_in_brief.init_sequence_todo. Use ${writeRegisterCall}`,
+        "     * and hal_delay_ms(). */",
+    ];
+}
+export function makeFiles(name, header, source, ext = { header: "h", source: "c" }) {
     return [
-        { path: `${name}.h`, content: `${header.join("\n").replace(/\n{3,}/g, "\n\n")}` },
-        { path: `${name}.c`, content: `${source.join("\n").replace(/\n{3,}/g, "\n\n")}` },
+        { path: `${name}.${ext.header}`, content: `${header.join("\n").replace(/\n{3,}/g, "\n\n")}` },
+        { path: `${name}.${ext.source}`, content: `${source.join("\n").replace(/\n{3,}/g, "\n\n")}` },
     ];
 }
-/** Render the portable thin-HAL driver skeleton for a validated datasheet. */
+/**
+ * Render the portable thin-HAL driver skeleton for a validated datasheet.
+ * DeviceInterface is a 2-member discriminated union, so narrowing on `kind`
+ * here — rather than casting inside registerDriver/commandDriver — lets both
+ * take an explicit, correctly-typed array with no cast. Any kind other than
+ * "command_set" is treated as register_map, matching buildInterface's
+ * register-first fallback (see schema/assemble) exactly.
+ */
 export function generatePortableDriver(json) {
     const part = json.metadata.part;
     const name = slug(part);
     const prefix = macro(name);
     return json.interface.kind === "command_set"
-        ? commandDriver(json, name, prefix)
-        : registerDriver(json, name, prefix);
+        ? commandDriver(json, json.interface.commands, name, prefix)
+        : registerDriver(json, json.interface.registers, name, prefix);
 }
 //# sourceMappingURL=portable.js.map