kit

posix.c (52122B)

---

 /* POSIX-shared environment: file I/O, mkdir, sigint, exec_dual registry,
  * single-mapping execmem, monotonic clock, stdin/edit, dlsym resolver,
  * driver_env_init for hosts where the POSIX TUs are compiled (Mac, Linux,
  * FreeBSD). Each function here behaves identically on those three; per-OS
  * specifics are isolated in macos.c / linux.c / freebsd.c. */
 
 #include <dirent.h>
 #include <errno.h>
 #include <fcntl.h>
 #include <pthread.h>
 #include <signal.h>
 #include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <sys/mman.h>
 #include <sys/stat.h>
 #include <sys/wait.h>
 #include <termios.h>
 #include <time.h>
 #include <unistd.h>
 
 #include "env_posix.h"
 
 extern char** environ;
 
 int driver_path_canonicalize(DriverEnv* env, const char* path, char** out,
                              size_t* out_size) {
   char* resolved;
   char* copy;
   size_t size;
   if (!env || !path || !path[0] || !out || !out_size) return 1;
   resolved = realpath(path, NULL);
   if (!resolved) return 1;
   size = driver_strlen(resolved) + 1u;
   copy = (char*)driver_alloc(env, size);
   if (!copy) {
     free(resolved);
     return 1;
   }
   driver_memcpy(copy, resolved, size);
   free(resolved);
   *out = copy;
   *out_size = size;
   return 0;
 }
 
 /* ---------------- exec memory: single-mapping core + registry ----------------
  */
 
 int kit_to_posix_prot(int prot) {
   int p = 0;
   if (prot & KIT_PROT_READ) p |= PROT_READ;
   if (prot & KIT_PROT_WRITE) p |= PROT_WRITE;
   if (prot & KIT_PROT_EXEC) p |= PROT_EXEC;
   return p;
 }
 
 /* Registry of EXEC reservations with distinct write/runtime aliases. The
  * dbg_os code_write_begin path uses this to translate a runtime address
  * into the corresponding write alias on dual-mapping hosts. Single-mapping
  * reservations (write == runtime) are not registered. JITs typically hold
  * 1-2 reservations live so a linked list keeps the lookup trivial. */
 typedef struct ExecDualNode {
   void* write_base;
   void* runtime_base;
   size_t size;
   struct ExecDualNode* next;
 } ExecDualNode;
 
 static ExecDualNode* g_jit_dual_map;
 static pthread_mutex_t g_jit_dual_map_mu = PTHREAD_MUTEX_INITIALIZER;
 
 void exec_dual_register(void* write_base, void* runtime_base, size_t size) {
   ExecDualNode* n;
   if (write_base == runtime_base) return;
   n = (ExecDualNode*)malloc(sizeof(*n));
   if (!n) return; /* registry is best-effort; lookup will fail open */
   n->write_base = write_base;
   n->runtime_base = runtime_base;
   n->size = size;
   pthread_mutex_lock(&g_jit_dual_map_mu);
   n->next = g_jit_dual_map;
   g_jit_dual_map = n;
   pthread_mutex_unlock(&g_jit_dual_map_mu);
 }
 
 void exec_dual_unregister(void* runtime_base) {
   ExecDualNode** pp;
   pthread_mutex_lock(&g_jit_dual_map_mu);
   for (pp = &g_jit_dual_map; *pp; pp = &(*pp)->next) {
     if ((*pp)->runtime_base == runtime_base) {
       ExecDualNode* dead = *pp;
       *pp = dead->next;
       free(dead);
       break;
     }
   }
   pthread_mutex_unlock(&g_jit_dual_map_mu);
 }
 
 int exec_dual_lookup(void* runtime_addr, size_t n, void** write_out) {
   ExecDualNode* cur;
   uintptr_t a = (uintptr_t)runtime_addr;
   pthread_mutex_lock(&g_jit_dual_map_mu);
   for (cur = g_jit_dual_map; cur; cur = cur->next) {
     uintptr_t base = (uintptr_t)cur->runtime_base;
     if (a >= base && a + n <= base + cur->size) {
       *write_out = (void*)((uintptr_t)cur->write_base + (a - base));
       pthread_mutex_unlock(&g_jit_dual_map_mu);
       return 0;
     }
   }
   pthread_mutex_unlock(&g_jit_dual_map_mu);
   return 1;
 }
 
 KitStatus execmem_reserve_single(size_t size, KitExecMemRegion* out) {
   void* p =
       mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANON, -1, 0);
   if (p == MAP_FAILED) return KIT_NOMEM;
   out->write = p;
   out->runtime = p;
   out->size = size;
   out->token = NULL; /* munmap suffices on release */
   return KIT_OK;
 }
 
 static KitStatus execmem_reserve(void* user, size_t size, int prot,
                                  KitExecMemRegion* out) {
   (void)user;
   if (!out || !size) return KIT_INVALID;
   if (prot & KIT_PROT_EXEC) return os_execmem_reserve_exec(size, out);
   return execmem_reserve_single(size, out);
 }
 
 static KitStatus execmem_protect(void* user, void* addr, size_t size,
                                  int prot) {
   (void)user;
   return mprotect(addr, size, kit_to_posix_prot(prot)) == 0 ? KIT_OK : KIT_ERR;
 }
 
 static void execmem_release(void* user, KitExecMemRegion* region) {
   (void)user;
   if (!region || !region->size) return;
   if (region->token) {
     ExecMemToken* tok = (ExecMemToken*)region->token;
     if (tok->runtime_addr && tok->runtime_addr != tok->write_addr) {
       exec_dual_unregister(tok->runtime_addr);
       munmap(tok->runtime_addr, tok->size);
     }
     if (tok->write_addr) munmap(tok->write_addr, tok->size);
     free(tok);
   } else if (region->write) {
     munmap(region->write, region->size);
   }
   region->write = NULL;
   region->runtime = NULL;
   region->size = 0;
   region->token = NULL;
 }
 
 static void execmem_flush_icache(void* user, void* addr, size_t size) {
   (void)user;
   env_flush_icache(addr, size);
 }
 
 size_t driver_host_page_size(void) {
   long p = sysconf(_SC_PAGESIZE);
   return (p > 0) ? (size_t)p : (size_t)0x4000;
 }
 
 KitExecMem g_execmem_posix; /* page_size set in driver_env_init */
 
 /* ---------------- fd writer ---------------- */
 
 /* Output is buffered: object emit and `-E` text both drive the writer in many
  * tiny chunks (a token, a 16-byte nlist entry), and one write() syscall per
  * chunk dominated compile/link wall time. The buffer coalesces them into
  * page-sized flushes. Invariant: the buffer holds a contiguous run ending at
  * the logical position `pos`, so the fd's real offset is always pos-buf_len;
  * every seek flushes first to keep that true. */
 #define FDW_BUF_CAP 65536u
 
 typedef struct DriverFdWriter {
   KitWriter base; /* must be first; libkit reads via this */
   KitHeap* heap;
   int fd;
   KitStatus status;
   uint64_t pos;   /* logical position of the next byte (incl. buffered) */
   size_t buf_len; /* bytes buffered but not yet written to fd */
   /* Atomic output: when set, bytes go to tmp_path and a successful close
    * renames it over final_path, so every build lands a *fresh inode*. This
    * avoids clobbering a still-referenced file and — crucially on macOS —
    * sidesteps the kernel's per-vnode code-signature cache, which otherwise
    * serves a stale "invalid signature" verdict for a re-signed executable
    * rewritten in place. NULL for plain fd writers (stdout, fallback). */
   char* tmp_path;
   char* final_path;
   unsigned char buf[FDW_BUF_CAP];
 } DriverFdWriter;
 
 /* Drain `data`/`n` straight to the fd (no buffering, no pos accounting). */
 static KitStatus fdw_raw(DriverFdWriter* fw, const unsigned char* p, size_t n) {
   while (n > 0) {
     ssize_t k = write(fw->fd, p, n);
     if (k < 0) {
       fw->status = KIT_IO;
       return KIT_IO;
     }
     p += (size_t)k;
     n -= (size_t)k;
   }
   return KIT_OK;
 }
 
 static KitStatus fdw_flush(DriverFdWriter* fw) {
   size_t n = fw->buf_len;
   if (n == 0) return fw->status;
   fw->buf_len = 0;
   return fdw_raw(fw, fw->buf, n);
 }
 
 static KitStatus fdw_write(KitWriter* w, const void* data, size_t n) {
   DriverFdWriter* fw = (DriverFdWriter*)w;
   const unsigned char* p = (const unsigned char*)data;
   if (fw->status != KIT_OK) return fw->status;
   if (n == 0) return KIT_OK;
   /* Large writes bypass the buffer: flush what is pending, then stream the
    * payload directly so a multi-MB section never round-trips through buf. */
   if (n >= FDW_BUF_CAP) {
     if (fdw_flush(fw) != KIT_OK) return fw->status;
     if (fdw_raw(fw, p, n) != KIT_OK) return fw->status;
     fw->pos += (uint64_t)n;
     return KIT_OK;
   }
   if (fw->buf_len + n > FDW_BUF_CAP) {
     if (fdw_flush(fw) != KIT_OK) return fw->status;
   }
   memcpy(fw->buf + fw->buf_len, p, n);
   fw->buf_len += n;
   fw->pos += (uint64_t)n;
   return KIT_OK;
 }
 
 static KitStatus fdw_seek(KitWriter* w, uint64_t off) {
   DriverFdWriter* fw = (DriverFdWriter*)w;
   if (fw->status != KIT_OK) return fw->status;
   if (fdw_flush(fw) != KIT_OK) return fw->status;
   if (lseek(fw->fd, (off_t)off, SEEK_SET) < 0) {
     fw->status = KIT_IO;
     return KIT_IO;
   }
   fw->pos = off;
   return KIT_OK;
 }
 
 static uint64_t fdw_tell(KitWriter* w) { return ((DriverFdWriter*)w)->pos; }
 static KitStatus fdw_status(KitWriter* w) {
   return ((DriverFdWriter*)w)->status;
 }
 
 static void fdw_close(KitWriter* w) {
   DriverFdWriter* fw = (DriverFdWriter*)w;
   KitStatus st;
   fdw_flush(fw);
   st = fw->status;
   if (fw->fd >= 0) {
     /* fsync the data before the rename so a crash can't leave the final
      * path pointing at a renamed-but-unflushed (truncated) file. */
     if (st == KIT_OK && fw->tmp_path && fsync(fw->fd) != 0) st = KIT_IO;
     if (close(fw->fd) != 0 && st == KIT_OK) st = KIT_IO;
   }
   if (fw->tmp_path) {
     if (st == KIT_OK && rename(fw->tmp_path, fw->final_path) != 0) {
       st = KIT_IO;
       fw->status = KIT_IO;
     }
     /* On any failure the temp never became the target: remove it so a failed
      * build leaves the previous output (if any) untouched and no litter. */
     if (st != KIT_OK) unlink(fw->tmp_path);
     fw->heap->free(fw->heap, fw->tmp_path, strlen(fw->tmp_path) + 1u);
     if (fw->final_path)
       fw->heap->free(fw->heap, fw->final_path, strlen(fw->final_path) + 1u);
   }
   fw->heap->free(fw->heap, fw, sizeof(*fw));
 }
 
 static KitWriter* driver_writer_fd(KitHeap* h, int fd) {
   DriverFdWriter* fw =
       (DriverFdWriter*)h->alloc(h, sizeof(*fw), _Alignof(DriverFdWriter));
   if (!fw) return NULL;
   fw->base.write = fdw_write;
   fw->base.seek = fdw_seek;
   fw->base.tell = fdw_tell;
   fw->base.status = fdw_status;
   fw->base.close = fdw_close;
   fw->heap = h;
   fw->fd = fd;
   fw->status = KIT_OK;
   fw->pos = 0;
   fw->buf_len = 0;
   fw->tmp_path = NULL;
   fw->final_path = NULL;
   return &fw->base;
 }
 
 /* Duplicate a NUL-terminated string into the heap (NULL on OOM). */
 static char* posix_strdup(KitHeap* h, const char* s) {
   size_t n = strlen(s) + 1u;
   char* p = (char*)h->alloc(h, n, 1);
   if (p) memcpy(p, s, n);
   return p;
 }
 
 /* Stdout writer routes through stdio so it shares libc's buffer with
  * driver_printf. */
 typedef struct DriverStdioWriter {
   KitWriter base;
   KitHeap* heap;
   FILE* fp;
   KitStatus status;
 } DriverStdioWriter;
 
 static KitStatus stdio_w_write(KitWriter* w, const void* data, size_t n) {
   DriverStdioWriter* sw = (DriverStdioWriter*)w;
   if (n) {
     size_t got = fwrite(data, 1, n, sw->fp);
     if (got != n) {
       sw->status = KIT_IO;
       return KIT_IO;
     }
   }
   return KIT_OK;
 }
 static KitStatus stdio_w_seek(KitWriter* w, uint64_t off) {
   DriverStdioWriter* sw = (DriverStdioWriter*)w;
   return fseek(sw->fp, (long)off, SEEK_SET) == 0 ? KIT_OK : KIT_IO;
 }
 static uint64_t stdio_w_tell(KitWriter* w) {
   long t = ftell(((DriverStdioWriter*)w)->fp);
   return t < 0 ? 0u : (uint64_t)t;
 }
 static KitStatus stdio_w_status(KitWriter* w) {
   DriverStdioWriter* sw = (DriverStdioWriter*)w;
   if (sw->status != KIT_OK) return sw->status;
   return ferror(sw->fp) ? KIT_IO : KIT_OK;
 }
 static void stdio_w_close(KitWriter* w) {
   DriverStdioWriter* sw = (DriverStdioWriter*)w;
   fflush(sw->fp); /* flush but do not close the borrowed stdio stream */
   sw->heap->free(sw->heap, sw, sizeof(*sw));
 }
 
 static KitWriter* driver_stdio_writer(DriverEnv* e, FILE* fp) {
   DriverStdioWriter* sw = (DriverStdioWriter*)e->heap->alloc(
       e->heap, sizeof(*sw), _Alignof(DriverStdioWriter));
   if (!sw) return NULL;
   sw->base.write = stdio_w_write;
   sw->base.seek = stdio_w_seek;
   sw->base.tell = stdio_w_tell;
   sw->base.status = stdio_w_status;
   sw->base.close = stdio_w_close;
   sw->heap = e->heap;
   sw->fp = fp;
   sw->status = KIT_OK;
   return &sw->base;
 }
 
 KitWriter* driver_stdout_writer(DriverEnv* e) {
   return driver_stdio_writer(e, stdout);
 }
 
 KitWriter* driver_stderr_writer(DriverEnv* e) {
   return driver_stdio_writer(e, stderr);
 }
 
 void driver_writer_abort(KitWriter* writer) {
   if (!writer) return;
   if (writer->close == fdw_close) {
     ((DriverFdWriter*)writer)->status = KIT_ERR;
   } else if (writer->close == stdio_w_close) {
     ((DriverStdioWriter*)writer)->status = KIT_ERR;
   }
 }
 
 const char* const* driver_environ(void) { return (const char* const*)environ; }
 
 /* ---------------- file_io (POSIX open/read/write/stat) ---------------- */
 
 static KitStatus posix_read_all(void* user, const char* path,
                                 KitFileData* out) {
   DriverEnv* env = (DriverEnv*)user;
   int fd;
   struct stat sb;
   size_t size;
   size_t got;
   void* buf;
 
   fd = open(path, O_RDONLY);
   if (fd < 0) return KIT_NOT_FOUND;
   if (fstat(fd, &sb) < 0) {
     close(fd);
     return KIT_IO;
   }
   size = (size_t)sb.st_size;
   buf = size ? env->heap->alloc(env->heap, size, 1) : NULL;
   if (size && !buf) {
     close(fd);
     return KIT_NOMEM;
   }
 
   got = 0;
   while (got < size) {
     ssize_t n = read(fd, (unsigned char*)buf + got, size - got);
     if (n <= 0) {
       env->heap->free(env->heap, buf, size);
       close(fd);
       return KIT_IO;
     }
     got += (size_t)n;
   }
   close(fd);
 
   out->data = (const uint8_t*)buf;
   out->size = size;
   out->token = buf;
   return KIT_OK;
 }
 
 static void posix_release(void* user, KitFileData* d) {
   DriverEnv* env = (DriverEnv*)user;
   if (d->token) env->heap->free(env->heap, d->token, d->size);
   d->data = NULL;
   d->size = 0;
   d->token = NULL;
 }
 
 /* Open `path` for output, atomically: write to a sibling temp file and rename
  * it over `path` on a clean close (see DriverFdWriter.tmp_path). The temp lives
  * in `path`'s own directory so the rename stays within one filesystem (a
  * cross-device rename would fail). Special files such as /dev/null are written
  * in place; regular file outputs must get a temp file or fail to open. */
 static KitStatus posix_open_writer(void* user, const char* path,
                                    KitWriter** out) {
   DriverEnv* env = (DriverEnv*)user;
   KitWriter* w;
   DriverFdWriter* fw;
   char tmpl[4096];
   const char* slash;
   size_t dlen;
   int fd;
   int via_temp = 0;
   struct stat sb;
 
   /* Only regular files (or not-yet-existing targets) get the temp+rename
    * treatment; special files must be written in place. */
   int special = (stat(path, &sb) == 0 && !S_ISREG(sb.st_mode));
 
   slash = strrchr(path, '/');
   dlen = slash ? (size_t)(slash - path) : 0u; /* dir part, "" => cwd */
   /* "<dir>/.kit-tmp-XXXXXX" (or ".kit-tmp-XXXXXX" in cwd). */
   if (!special && dlen + sizeof(".kit-tmp-XXXXXX") + 1u <= sizeof(tmpl)) {
     if (dlen) {
       memcpy(tmpl, path, dlen);
       tmpl[dlen] = '/';
       memcpy(tmpl + dlen + 1u, ".kit-tmp-XXXXXX", sizeof(".kit-tmp-XXXXXX"));
     } else {
       memcpy(tmpl, ".kit-tmp-XXXXXX", sizeof(".kit-tmp-XXXXXX"));
     }
     fd = mkstemp(tmpl);
     if (fd >= 0) {
       /* mkstemp creates 0600; match the in-place 0644 (the +x bit, when an
        * executable, is applied to the final path after close). */
       (void)fchmod(fd, 0644);
       via_temp = 1;
     } else {
       return KIT_IO;
     }
   } else if (special) {
     fd = open(path, O_WRONLY | O_CREAT | O_TRUNC, 0644);
   } else {
     return KIT_IO;
   }
   if (fd < 0) return KIT_IO;
 
   w = driver_writer_fd(env->heap, fd);
   if (!w) {
     close(fd);
     if (via_temp) unlink(tmpl);
     return KIT_NOMEM;
   }
   if (via_temp) {
     fw = (DriverFdWriter*)w;
     fw->tmp_path = posix_strdup(env->heap, tmpl);
     fw->final_path = posix_strdup(env->heap, path);
     if (!fw->tmp_path || !fw->final_path) {
       /* Without both paths we can't rename; degrade to leaving the temp in
        * place would be wrong, so fail cleanly. */
       if (fw->tmp_path)
         env->heap->free(env->heap, fw->tmp_path, strlen(tmpl) + 1u);
       if (fw->final_path)
         env->heap->free(env->heap, fw->final_path, strlen(path) + 1u);
       fw->tmp_path = NULL;
       fw->final_path = NULL;
       fdw_close(w);
       unlink(tmpl);
       return KIT_NOMEM;
     }
   }
   *out = w;
   return KIT_OK;
 }
 
 /* ---------------- path helpers ---------------- */
 
 int driver_path_exists(const char* path) {
   struct stat sb;
   if (!path) return 0;
   return stat(path, &sb) == 0;
 }
 
 int driver_path_mtime_ns(const char* path, int64_t* out) {
   struct stat sb;
   if (!path || !out) return 1;
   if (stat(path, &sb) != 0) return 1;
   return os_stat_mtime_ns(&sb, out);
 }
 
 static uint8_t posix_mode_to_wasm_filetype(mode_t m) {
   if (S_ISREG(m)) return 4;
   if (S_ISDIR(m)) return 3;
   if (S_ISLNK(m)) return 7;
   if (S_ISBLK(m)) return 1;
   if (S_ISCHR(m)) return 2;
   if (S_ISSOCK(m)) return 6;
   return 0;
 }
 
 int driver_path_stat(const char* path, uint64_t* out_size,
                      uint64_t* out_mtime_ns, uint8_t* out_filetype) {
   struct stat sb;
   int64_t mtime;
   if (!path || stat(path, &sb) != 0)
     return (errno == ENOENT || errno == ENOTDIR) ? 1 : 2;
   *out_size = (uint64_t)sb.st_size;
   *out_mtime_ns = os_stat_mtime_ns(&sb, &mtime) == 0 ? (uint64_t)mtime : 0u;
   *out_filetype = posix_mode_to_wasm_filetype(sb.st_mode);
   return 0;
 }
 
 int driver_path_lstat(const char* path, uint64_t* out_size,
                       uint8_t* out_filetype, int* out_executable) {
   struct stat sb;
   if (!path || lstat(path, &sb) != 0)
     return (errno == ENOENT || errno == ENOTDIR) ? 1 : 2;
   *out_size = (uint64_t)sb.st_size;
   *out_filetype = posix_mode_to_wasm_filetype(sb.st_mode);
   *out_executable =
       S_ISREG(sb.st_mode) && (sb.st_mode & (S_IXUSR | S_IXGRP | S_IXOTH)) != 0;
   return 0;
 }
 
 typedef struct DriverDirEntryRec {
   char* name;
   size_t name_alloc;
   uint32_t name_len;
   uint64_t ino;
   uint64_t size;
   uint64_t mtime_ns;
   uint8_t filetype;
 } DriverDirEntryRec;
 
 struct DriverDirHandle {
   DriverEnv* env;
   DriverDirEntryRec* entries;
   size_t entries_alloc;
   uint64_t count;
 };
 
 DriverDirHandle* driver_open_dir(DriverEnv* env, const char* path) {
   DIR* d;
   struct dirent* ent;
   DriverDirHandle* h;
   uint64_t cap = 0;
   uint64_t count = 0;
   size_t plen;
   int slash;
 
   if (!env || !path) return NULL;
   d = opendir(path);
   if (!d) return NULL;
   plen = kit_slice_cstr(path).len;
   slash = plen && path[plen - 1u] != '/';
 
   h = (DriverDirHandle*)env->heap->alloc(env->heap, sizeof(*h),
                                          _Alignof(DriverDirHandle));
   if (!h) {
     closedir(d);
     return NULL;
   }
   memset(h, 0, sizeof(*h));
   h->env = env;
 
   while ((ent = readdir(d)) != NULL) {
     const char* name = ent->d_name;
     size_t name_len;
     DriverDirEntryRec* e;
     size_t child_alloc;
     char* child;
     struct stat sb;
     int64_t mtime;
 
     if (driver_streq(name, ".") || driver_streq(name, "..")) continue;
     name_len = kit_slice_cstr(name).len;
 
     /* grow entry array */
     if (count >= cap) {
       uint64_t new_cap = cap ? cap * 2u : 8u;
       size_t new_alloc = (size_t)new_cap * sizeof(DriverDirEntryRec);
       DriverDirEntryRec* nv = (DriverDirEntryRec*)env->heap->alloc(
           env->heap, new_alloc, _Alignof(DriverDirEntryRec));
       if (!nv) goto fail;
       if (h->entries) {
         memcpy(nv, h->entries, (size_t)count * sizeof(DriverDirEntryRec));
         env->heap->free(env->heap, h->entries, h->entries_alloc);
       }
       h->entries = nv;
       h->entries_alloc = new_alloc;
       cap = new_cap;
     }
 
     e = &h->entries[count];
     memset(e, 0, sizeof(*e));
     e->name_alloc = name_len + 1u;
     e->name = (char*)env->heap->alloc(env->heap, e->name_alloc, 1u);
     if (!e->name) goto fail;
     memcpy(e->name, name, name_len);
     e->name[name_len] = '\0';
     e->name_len = (uint32_t)name_len;
 
     /* lstat the entry to get metadata */
     child_alloc = plen + (size_t)slash + name_len + 1u;
     child = (char*)driver_alloc(env, child_alloc);
     if (child) {
       size_t off = 0;
       memcpy(child, path, plen);
       off += plen;
       if (slash) child[off++] = '/';
       memcpy(child + off, name, name_len);
       child[off + name_len] = '\0';
       if (lstat(child, &sb) == 0) {
         e->ino = (uint64_t)sb.st_ino;
         e->size = (uint64_t)sb.st_size;
         if (os_stat_mtime_ns(&sb, &mtime) == 0) e->mtime_ns = (uint64_t)mtime;
         e->filetype = posix_mode_to_wasm_filetype(sb.st_mode);
       }
       driver_free(env, child, child_alloc);
     }
     ++count;
   }
 
   closedir(d);
   h->count = count;
   return h;
 
 fail:
   closedir(d);
   driver_close_dir(env, h);
   return NULL;
 }
 
 int driver_read_dir_entry(DriverDirHandle* h, uint64_t index,
                           const char** out_name, uint32_t* out_name_len,
                           uint64_t* out_ino, uint64_t* out_size,
                           uint64_t* out_mtime_ns, uint8_t* out_filetype) {
   DriverDirEntryRec* e;
   if (!h || index >= h->count) return 1;
   e = &h->entries[index];
   *out_name = e->name;
   *out_name_len = e->name_len;
   *out_ino = e->ino;
   *out_size = e->size;
   *out_mtime_ns = e->mtime_ns;
   *out_filetype = e->filetype;
   return 0;
 }
 
 void driver_close_dir(DriverEnv* env, DriverDirHandle* h) {
   uint64_t i;
   if (!h) return;
   if (!env) env = h->env;
   for (i = 0; i < h->count; ++i) {
     DriverDirEntryRec* e = &h->entries[i];
     if (e->name) env->heap->free(env->heap, e->name, e->name_alloc);
   }
   if (h->entries) env->heap->free(env->heap, h->entries, h->entries_alloc);
   env->heap->free(env->heap, h, sizeof(*h));
 }
 
 int driver_mkdir_p(DriverEnv* env, const char* path) {
   size_t len;
   char* buf;
   size_t i;
   struct stat sb;
 
   if (!path || !path[0]) return 1;
   len = kit_slice_cstr(path).len;
   buf = (char*)driver_alloc(env, len + 1);
   if (!buf) return 1;
   memcpy(buf, path, len + 1);
 
   for (i = 1; i <= len; ++i) {
     int at_end = (i == len);
     if (!at_end && buf[i] != '/') continue;
     if (!at_end) buf[i] = '\0';
     if (buf[0] != '\0' && !driver_streq(buf, ".")) {
       if (mkdir(buf, 0755) != 0 && errno != EEXIST) {
         driver_free(env, buf, len + 1);
         return 1;
       }
       if (stat(buf, &sb) != 0 || !S_ISDIR(sb.st_mode)) {
         driver_free(env, buf, len + 1);
         return 1;
       }
     }
     if (!at_end) buf[i] = '/';
   }
 
   driver_free(env, buf, len + 1);
   return 0;
 }
 
 int driver_mark_executable_output(const char* path) {
   mode_t mask;
   mode_t mode;
   if (!path) return 1;
   mask = umask(0);
   (void)umask(mask);
   mode = (mode_t)(0777 & ~mask);
   return chmod(path, mode) == 0 ? 0 : 1;
 }
 
 int driver_path_mode_get(const char* path, uint32_t* mode_out) {
   struct stat sb;
   if (!path || !mode_out || stat(path, &sb) != 0 || !S_ISREG(sb.st_mode))
     return 1;
   *mode_out = (uint32_t)(sb.st_mode & 07777u);
   return 0;
 }
 
 int driver_path_mode_set(const char* path, uint32_t mode) {
   if (!path || mode > 07777u) return 1;
   return chmod(path, (mode_t)mode) == 0 ? 0 : 1;
 }
 
 /* ---------------- link helpers (install) ---------------- */
 
 int driver_create_symlink(const char* target, const char* link_path) {
   if (!target || !link_path) return 1;
   return symlink(target, link_path) == 0 ? 0 : 1;
 }
 
 int driver_readlink(const char* path, char* buf, size_t cap) {
   ssize_t n;
   if (!path || !buf || cap == 0) return 1;
   /* Read into the full buffer; readlink never NUL-terminates and reports the
    * untruncated length, so n >= cap means the target did not fit. */
   n = readlink(path, buf, cap);
   if (n < 0) return 1;
   if ((size_t)n >= cap) return 1;
   buf[n] = '\0';
   return 0;
 }
 
 int driver_create_hardlink(const char* target, const char* link_path) {
   if (!target || !link_path) return 1;
   return link(target, link_path) == 0 ? 0 : 1;
 }
 
 int driver_remove_file(const char* path) {
   if (!path) return 1;
   if (unlink(path) == 0) return 0;
   return errno == ENOENT ? 0 : 1; /* already absent is success */
 }
 
 int driver_path_lexists(const char* path) {
   struct stat sb;
   if (!path) return 0;
   return lstat(path, &sb) == 0;
 }
 
 int driver_rename(const char* from, const char* to) {
   if (!from || !to) return 1;
   return rename(from, to) == 0 ? 0 : 1; /* same-fs rename is atomic */
 }
 
 static int posix_remove_tree(const char* path) {
   struct stat sb;
   if (lstat(path, &sb) != 0) return errno == ENOENT ? 0 : 1;
   if (S_ISDIR(sb.st_mode)) { /* lstat: a symlink-to-dir is unlinked, not entered */
     DIR* d = opendir(path);
     struct dirent* ent;
     int rc = 0;
     if (!d) return 1;
     while ((ent = readdir(d)) != NULL) {
       char child[4096];
       const char* name = ent->d_name;
       if (name[0] == '.' &&
           (name[1] == '\0' || (name[1] == '.' && name[2] == '\0')))
         continue;
       if ((size_t)snprintf(child, sizeof child, "%s/%s", path, name) >=
           sizeof child) {
         rc = 1;
         continue;
       }
       if (posix_remove_tree(child) != 0) rc = 1;
     }
     closedir(d);
     if (rmdir(path) != 0) rc = 1;
     return rc;
   }
   return unlink(path) == 0 ? 0 : 1;
 }
 
 int driver_remove_tree(const char* path) {
   if (!path) return 1;
   return posix_remove_tree(path);
 }
 
 int driver_kit_home(char* buf, size_t cap) {
   const char* v;
   int n = -1;
   size_t len;
   if (!buf || cap == 0) return 1;
   if ((v = getenv("KIT_HOME")) && *v)
     n = snprintf(buf, cap, "%s", v);
   else if ((v = getenv("XDG_DATA_HOME")) && *v)
     n = snprintf(buf, cap, "%s/kit", v);
   else if ((v = getenv("HOME")) && *v)
     n = snprintf(buf, cap, "%s/.local/share/kit", v);
   if (n < 0 || (size_t)n >= cap) return 1;
   len = strlen(buf);
   while (len > 1 && buf[len - 1] == '/') buf[--len] = '\0'; /* no trailing '/' */
   return 0;
 }
 
 static int fetch_hex_val(char c, unsigned* out) {
   if (c >= '0' && c <= '9') {
     *out = (unsigned)(c - '0');
     return 0;
   }
   if (c >= 'a' && c <= 'f') {
     *out = (unsigned)(c - 'a') + 10u;
     return 0;
   }
   if (c >= 'A' && c <= 'F') {
     *out = (unsigned)(c - 'A') + 10u;
     return 0;
   }
   return 1;
 }
 
 static char* fetch_decode_url_path(const char* s) {
   char* out;
   char* w;
   size_t n;
   if (!s) return NULL;
   n = strlen(s);
   out = (char*)malloc(n + 1u);
   if (!out) return NULL;
   w = out;
   while (*s) {
     if (*s == '%') {
       unsigned hi, lo;
       if (!s[1] || !s[2] || fetch_hex_val(s[1], &hi) ||
           fetch_hex_val(s[2], &lo)) {
         free(out);
         return NULL;
       }
       if (((hi << 4) | lo) == 0u) {
         free(out);
         return NULL;
       }
       *w++ = (char)((hi << 4) | lo);
       s += 3;
     } else {
       *w++ = *s++;
     }
   }
   *w = '\0';
   return out;
 }
 
 static char* fetch_file_url_path(const char* url) {
   const char* p;
   if (!url || strncmp(url, "file://", 7) != 0) return NULL;
   p = url + 7;
   if (strncmp(p, "localhost/", 10) == 0) {
     p += 9; /* keep the slash before the absolute path */
   } else if (p[0] != '/') {
     return NULL;
   }
   return fetch_decode_url_path(p);
 }
 
 static int fetch_copy_file(const char* src, const char* dest) {
   uint8_t buf[32768];
   int in_fd, out_fd;
   int rc = 1;
   if (!src || !dest) return 1;
   in_fd = open(src, O_RDONLY);
   if (in_fd < 0) return 1;
   out_fd = open(dest, O_WRONLY | O_CREAT | O_TRUNC, 0666);
   if (out_fd < 0) {
     close(in_fd);
     return 1;
   }
   for (;;) {
     ssize_t r = read(in_fd, buf, sizeof buf);
     size_t off = 0;
     if (r == 0) {
       rc = 0;
       break;
     }
     if (r < 0) {
       if (errno == EINTR) continue;
       break;
     }
     while (off < (size_t)r) {
       ssize_t w = write(out_fd, buf + off, (size_t)r - off);
       if (w > 0) {
         off += (size_t)w;
       } else if (w < 0 && errno == EINTR) {
         continue;
       } else {
         goto out;
       }
     }
   }
 out:
   if (close(out_fd) != 0) rc = 1;
   close(in_fd);
   return rc;
 }
 
 int driver_fetch_url(const char* url, const char* dest) {
   pid_t pid;
   int status;
   char* file_path;
   if (!url || !dest) return 1;
   if (strncmp(url, "file://", 7) == 0) {
     int rc;
     file_path = fetch_file_url_path(url);
     if (!file_path) return 1;
     rc = fetch_copy_file(file_path, dest);
     free(file_path);
     return rc;
   }
   pid = fork();
   if (pid < 0) return 1;
   if (pid == 0) {
     /* Untrusted transport: the URL is a distinct argv element (no shell), so a
      * hostile mirror URL cannot inject a command. The production update
      * transport is deliberately curl-only so its TLS and redirect behavior is
      * one audited contract rather than whichever downloader happens to be
      * installed first. */
     execlp("curl", "curl", "-fsSL", "-o", dest, "--", url, (char*)NULL);
     _exit(127);
   }
   do {
     if (waitpid(pid, &status, 0) < 0) {
       if (errno == EINTR) continue;
       return 1;
     }
     break;
   } while (1);
   return (WIFEXITED(status) && WEXITSTATUS(status) == 0) ? 0 : 1;
 }
 
 int driver_touch(const char* path) {
   const struct timespec times[2] = {{0, UTIME_NOW}, {0, UTIME_NOW}};
   if (!path) return 1;
   if (utimensat(AT_FDCWD, path, times, 0) == 0) return 0;
   if (errno == ENOENT) {
     int fd = open(path, O_WRONLY | O_CREAT, 0666);
     if (fd >= 0) {
       close(fd);
       return 0;
     }
   }
   return 1;
 }
 
 static int driver_walk_regular_files_at(DriverEnv* env, const char* dir,
                                         const char* rel, DriverWalkFileFn cb,
                                         void* user) {
   DIR* d;
   struct dirent* ent;
   int rc = 1;
   d = opendir(dir);
   if (!d) return 1;
   while ((ent = readdir(d)) != NULL) {
     const char* name = ent->d_name;
     char* child;
     char* child_rel;
     struct stat sb;
     int child_rc = 0;
     if (driver_streq(name, ".") || driver_streq(name, "..")) continue;
     child = driver_path_join(env, dir, name, NULL);
     if (!child) goto out;
     child_rel = rel && rel[0] ? driver_path_join(env, rel, name, NULL)
                               : driver_path_join(env, "", name, NULL);
     if (!child_rel) {
       driver_free(env, child, kit_slice_cstr(child).len + 1u);
       goto out;
     }
     if (lstat(child, &sb) != 0) {
       child_rc = 1;
     } else if (S_ISDIR(sb.st_mode)) {
       child_rc = driver_walk_regular_files_at(env, child, child_rel, cb, user);
     } else if (S_ISREG(sb.st_mode)) {
       int x = (sb.st_mode & (S_IXUSR | S_IXGRP | S_IXOTH)) != 0;
       child_rc = cb(user, child, child_rel, x);
     } else {
       child_rc = 1;
     }
     driver_free(env, child_rel, kit_slice_cstr(child_rel).len + 1u);
     driver_free(env, child, kit_slice_cstr(child).len + 1u);
     if (child_rc) goto out;
   }
   rc = 0;
 
 out:
   closedir(d);
   return rc;
 }
 
 int driver_walk_regular_files(DriverEnv* env, const char* root,
                               DriverWalkFileFn cb, void* user) {
   if (!env || !root || !root[0] || !cb) return 1;
   return driver_walk_regular_files_at(env, root, "", cb, user);
 }
 
 /* ---------------- time ---------------- */
 
 uint64_t driver_now_ns(void) {
   struct timespec ts;
   if (clock_gettime(CLOCK_MONOTONIC, &ts) == 0)
     return (uint64_t)ts.tv_sec * 1000000000ull + (uint64_t)ts.tv_nsec;
   return 0;
 }
 
 int driver_random_bytes(uint8_t* out, size_t n) {
   /* /dev/urandom is the most portable CSPRNG across darwin/linux/freebsd and
    * avoids getentropy()'s per-platform header/feature-macro gymnastics. */
   size_t off = 0;
   int fd;
   if (!out) return 1;
   fd = open("/dev/urandom", O_RDONLY);
   if (fd < 0) return 1;
   while (off < n) {
     ssize_t r = read(fd, out + off, n - off);
     if (r > 0) {
       off += (size_t)r;
     } else if (r < 0 && errno == EINTR) {
       continue;
     } else {
       close(fd);
       return 1;
     }
   }
   close(fd);
   return 0;
 }
 
 /* ---------------- load helpers ---------------- */
 
 /* driver_load_bytes / driver_release_bytes are OS-neutral; see env/common.c. */
 
 /* ---------------- stdin / edit_temp / read_line ---------------- */
 
 int driver_read_stdin(DriverEnv* e, uint8_t** out_data, size_t* out_size) {
   size_t cap = 4096;
   size_t len = 0;
   uint8_t* buf = e->heap->alloc(e->heap, cap, 1);
   if (!buf) return 0;
   for (;;) {
     ssize_t n;
     if (len == cap) {
       size_t newcap = cap * 2;
       uint8_t* nb = e->heap->realloc(e->heap, buf, cap, newcap, 1);
       if (!nb) {
         e->heap->free(e->heap, buf, cap);
         return 0;
       }
       buf = nb;
       cap = newcap;
     }
     n = read(STDIN_FILENO, buf + len, cap - len);
     if (n == 0) break;
     if (n < 0) {
       e->heap->free(e->heap, buf, cap);
       return 0;
     }
     len += (size_t)n;
   }
   if (len < cap) {
     uint8_t* shrunk = len ? e->heap->realloc(e->heap, buf, cap, len, 1) : NULL;
     if (len && !shrunk) {
       *out_data = buf;
       *out_size = cap;
       return 1;
     }
     if (!len) {
       e->heap->free(e->heap, buf, cap);
       buf = NULL;
     } else {
       buf = shrunk;
     }
   }
   *out_data = buf;
   *out_size = len;
   return 1;
 }
 
 static int driver_write_fd_all(int fd, const uint8_t* data, size_t n) {
   size_t off = 0;
   while (off < n) {
     ssize_t wr = write(fd, data + off, n - off);
     if (wr < 0) {
       if (errno == EINTR) continue;
       return 0;
     }
     if (wr == 0) return 0;
     off += (size_t)wr;
   }
   return 1;
 }
 
 static char* driver_shell_quote_path(DriverEnv* e, const char* path,
                                      size_t path_len, size_t* quoted_len_out) {
   size_t i;
   size_t quoted_len = 2u;
   char* out;
   char* q;
   for (i = 0; i < path_len; ++i) quoted_len += path[i] == '\'' ? 4u : 1u;
   out = e->heap->alloc(e->heap, quoted_len + 1u, 1);
   if (!out) return NULL;
   q = out;
   *q++ = '\'';
   for (i = 0; i < path_len; ++i) {
     if (path[i] == '\'') {
       *q++ = '\'';
       *q++ = '\\';
       *q++ = '\'';
       *q++ = '\'';
     } else {
       *q++ = path[i];
     }
   }
   *q++ = '\'';
   *q = '\0';
   if (quoted_len_out) *quoted_len_out = quoted_len;
   return out;
 }
 
 int driver_edit_temp(DriverEnv* e, const char* suffix, const uint8_t* initial,
                      size_t initial_size, uint8_t** out_data,
                      size_t* out_size) {
   const char* editor;
   const char* tmpdir;
   const char* base = "/kit-dbg-XXXXXX";
   size_t tmpdir_len;
   size_t base_len;
   size_t suffix_len;
   size_t path_len;
   char* path;
   int fd = -1;
   int ok = 0;
   KitFileData fd_data;
 
   if (!out_data || !out_size) return 0;
   *out_data = NULL;
   *out_size = 0;
   suffix_len = suffix ? kit_slice_cstr(suffix).len : 0u;
   tmpdir = getenv("TMPDIR");
   if (!tmpdir || !*tmpdir) tmpdir = "/tmp";
   tmpdir_len = kit_slice_cstr(tmpdir).len;
   base_len = kit_slice_cstr(base).len;
   path_len = tmpdir_len + base_len + suffix_len;
   path = e->heap->alloc(e->heap, path_len + 1u, 1);
   if (!path) return 0;
   memcpy(path, tmpdir, tmpdir_len);
   memcpy(path + tmpdir_len, base, base_len);
   if (suffix_len) memcpy(path + tmpdir_len + base_len, suffix, suffix_len);
   path[path_len] = '\0';
 
   fd = mkstemps(path, (int)suffix_len);
   if (fd < 0) goto out;
   if (initial_size &&
       !driver_write_fd_all(fd, initial ? initial : (const uint8_t*)"",
                            initial_size))
     goto out;
   if (close(fd) != 0) {
     fd = -1;
     goto out;
   }
   fd = -1;
 
   editor = getenv("VISUAL");
   if (!editor || !*editor) editor = getenv("EDITOR");
   if (!editor || !*editor) editor = "vi";
   {
     size_t editor_len = kit_slice_cstr(editor).len;
     size_t quoted_len = 0;
     char* quoted = driver_shell_quote_path(e, path, path_len, &quoted_len);
     char* cmd;
     int status;
     pid_t pid;
     if (!quoted) goto out;
     cmd = e->heap->alloc(e->heap, editor_len + 1u + quoted_len + 1u, 1);
     if (!cmd) {
       e->heap->free(e->heap, quoted, quoted_len + 1u);
       goto out;
     }
     memcpy(cmd, editor, editor_len);
     cmd[editor_len] = ' ';
     memcpy(cmd + editor_len + 1u, quoted, quoted_len + 1u);
     e->heap->free(e->heap, quoted, quoted_len + 1u);
     pid = fork();
     if (pid == 0) {
       execl("/bin/sh", "sh", "-c", cmd, (char*)NULL);
       _exit(127);
     }
     e->heap->free(e->heap, cmd, editor_len + 1u + quoted_len + 1u);
     if (pid < 0) goto out;
     do {
       if (waitpid(pid, &status, 0) < 0) {
         if (errno == EINTR) continue;
         goto out;
       }
       break;
     } while (1);
     if (!WIFEXITED(status) || WEXITSTATUS(status) != 0) goto out;
   }
 
   fd_data.data = NULL;
   fd_data.size = 0;
   fd_data.token = NULL;
   if (posix_read_all(e, path, &fd_data) != KIT_OK) goto out;
   *out_data = (uint8_t*)fd_data.data;
   *out_size = fd_data.size;
   ok = 1;
 
 out:
   if (fd >= 0) close(fd);
   if (path) {
     unlink(path);
     e->heap->free(e->heap, path, path_len + 1u);
   }
   return ok;
 }
 
 int driver_read_line(char* buf, size_t cap) {
   size_t len = 0;
   if (!buf || cap < 2) return -1;
   for (;;) {
     int c;
     errno = 0;
     c = fgetc(stdin);
     if (c == EOF) {
       buf[len] = '\0';
       if (errno == EINTR) {
         clearerr(stdin);
         return -2;
       }
       if (ferror(stdin)) return -1;
       if (len == 0) return 0;
       return (int)len;
     }
     if (c == '\n') {
       buf[len] = '\0';
       return (int)len;
     }
     if (len + 1 < cap) buf[len++] = (char)c;
   }
 }
 
 static void line_completion_list_fini(DriverLineCompletionList* l) {
   uint32_t i;
   if (!l || !l->env) return;
   for (i = 0; i < l->count; ++i) {
     if (l->items[i].text)
       driver_free(l->env, l->items[i].text, l->items[i].size);
   }
   if (l->items)
     driver_free(l->env, l->items, (size_t)l->cap * sizeof(*l->items));
 }
 
 static int line_history_add(DriverEnv* env, DriverLineHistory* h,
                             const char* line, size_t len) {
   char** ni;
   size_t* ns;
   char* copy;
   uint32_t nc;
   size_t old_items_size;
   size_t new_items_size;
   size_t old_sizes_size;
   size_t new_sizes_size;
   if (!env || !h || !line || len == 0) return 0;
   if (h->count > 0 && h->items[h->count - 1] &&
       strlen(h->items[h->count - 1]) == len &&
       memcmp(h->items[h->count - 1], line, len) == 0)
     return 0;
   if (h->count == h->cap) {
     nc = h->cap ? h->cap * 2u : 32u;
     old_items_size = (size_t)h->cap * sizeof(*h->items);
     new_items_size = (size_t)nc * sizeof(*h->items);
     old_sizes_size = (size_t)h->cap * sizeof(*h->sizes);
     new_sizes_size = (size_t)nc * sizeof(*h->sizes);
     ni = (char**)env->heap->realloc(env->heap, h->items, old_items_size,
                                     new_items_size, _Alignof(char*));
     if (!ni) return 1;
     h->items = ni;
     ns = (size_t*)env->heap->realloc(env->heap, h->sizes, old_sizes_size,
                                      new_sizes_size, _Alignof(size_t));
     if (!ns) return 1;
     h->sizes = ns;
     h->cap = nc;
   }
   copy = (char*)driver_alloc(env, len + 1u);
   if (!copy) return 1;
   memcpy(copy, line, len);
   copy[len] = '\0';
   h->items[h->count] = copy;
   h->sizes[h->count] = len + 1u;
   h->count++;
   return 0;
 }
 
 static void line_redraw(const char* prompt, const char* buf, size_t len,
                         size_t cursor) {
   size_t back = len - cursor;
   fputc('\r', stdout);
   fputs(prompt, stdout);
   if (len) fwrite(buf, 1, len, stdout);
   fputs("\033[K", stdout);
   if (back) fprintf(stdout, "\033[%zuD", back);
   fflush(stdout);
 }
 
 static void line_set(char* buf, size_t cap, size_t* len, size_t* cursor,
                      const char* src) {
   size_t n = strlen(src);
   if (n >= cap) n = cap - 1u;
   memmove(buf, src, n);
   buf[n] = '\0';
   *len = n;
   *cursor = n;
 }
 
 static int line_replace(char* buf, size_t cap, size_t* len, size_t* cursor,
                         size_t start, size_t end, const char* rep,
                         size_t rep_len) {
   size_t tail;
   if (start > end || end > *len) return 1;
   tail = *len - end;
   if (start + rep_len + tail + 1u > cap) return 1;
   memmove(buf + start + rep_len, buf + end, tail + 1u);
   if (rep_len) memcpy(buf + start, rep, rep_len);
   *len = start + rep_len + tail;
   *cursor = start + rep_len;
   return 0;
 }
 
 static size_t line_common_prefix(const DriverLineCompletionList* l) {
   size_t n;
   uint32_t i;
   if (!l || l->count == 0) return 0;
   n = strlen(l->items[0].text);
   for (i = 1; i < l->count; ++i) {
     size_t j = 0;
     const char* s = l->items[i].text;
     while (j < n && s[j] && s[j] == l->items[0].text[j]) ++j;
     n = j;
   }
   return n;
 }
 
 static void line_default_complete_range(const char* buf, size_t cursor,
                                         size_t* start, size_t* end) {
   size_t s = cursor;
   while (s > 0 && buf[s - 1] != ' ' && buf[s - 1] != '\t') --s;
   *start = s;
   *end = cursor;
 }
 
 static void line_complete(DriverEnv* env, char* buf, size_t cap, size_t* len,
                           size_t* cursor, const char* prompt,
                           DriverLineCompleteFn complete, void* complete_user) {
   DriverLineCompletionList list;
   size_t common;
   size_t cur_len;
   uint32_t i;
   if (!complete) return;
   {
     DriverLineCompletionList z = {0};
     list = z;
   }
   list.env = env;
   line_default_complete_range(buf, *cursor, &list.replace_start,
                               &list.replace_end);
   complete(complete_user, buf, *cursor, &list);
   if (list.replace_end > *len) list.replace_end = *len;
   if (list.replace_start > list.replace_end)
     list.replace_start = list.replace_end;
   if (list.count == 1) {
     size_t rn = strlen(list.items[0].text);
     if (line_replace(buf, cap, len, cursor, list.replace_start,
                      list.replace_end, list.items[0].text, rn) != 0)
       fputc('\a', stdout);
     line_redraw(prompt, buf, *len, *cursor);
     line_completion_list_fini(&list);
     return;
   }
   if (list.count > 1) {
     common = line_common_prefix(&list);
     cur_len = *cursor > list.replace_start ? *cursor - list.replace_start : 0;
     if (common > cur_len) {
       if (line_replace(buf, cap, len, cursor, list.replace_start,
                        list.replace_end, list.items[0].text, common) != 0)
         fputc('\a', stdout);
       line_redraw(prompt, buf, *len, *cursor);
     } else {
       fputc('\n', stdout);
       for (i = 0; i < list.count; ++i)
         fprintf(stdout, "  %s\n", list.items[i].text);
       line_redraw(prompt, buf, *len, *cursor);
     }
   } else {
     fputc('\a', stdout);
     fflush(stdout);
   }
   line_completion_list_fini(&list);
 }
 
 int driver_read_line_edit(DriverEnv* env, const char* prompt, char* buf,
                           size_t cap, DriverLineHistory* hist,
                           DriverLineCompleteFn complete, void* complete_user,
                           const char* edit_suffix) {
   struct termios orig;
   struct termios raw;
   char* saved = NULL;
   size_t saved_size = 0;
   size_t len = 0;
   size_t cursor = 0;
   uint32_t hist_pos = 0;
   int have_saved = 0;
   int raw_enabled = 0;
   int out_rc = -1;
 
   if (!buf || cap < 2) return -1;
   if (!prompt) prompt = "";
   if (!isatty(STDIN_FILENO) || !isatty(STDOUT_FILENO)) {
     int n;
     fputs(prompt, stdout);
     fflush(stdout);
     n = driver_read_line(buf, cap);
     if (n > 0 && hist) (void)line_history_add(env, hist, buf, (size_t)n);
     return n;
   }
 
   if (tcgetattr(STDIN_FILENO, &orig) != 0) goto out;
   raw = orig;
   raw.c_lflag &= (tcflag_t) ~(ICANON | ECHO | IEXTEN);
   raw.c_iflag &= (tcflag_t) ~(IXON);
   raw.c_cc[VMIN] = 1;
   raw.c_cc[VTIME] = 0;
   if (tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw) != 0) goto out;
   raw_enabled = 1;
 
   saved = (char*)driver_alloc(env, cap);
   if (!saved) goto out;
   saved_size = cap;
   hist_pos = hist ? hist->count : 0;
   buf[0] = '\0';
 
   fputs(prompt, stdout);
   fflush(stdout);
   for (;;) {
     unsigned char c;
     ssize_t r = read(STDIN_FILENO, &c, 1);
     if (r < 0) {
       if (errno == EINTR) {
         out_rc = -2;
         goto out;
       }
       out_rc = -1;
       goto out;
     }
     if (r == 0) {
       out_rc = len ? (int)len : 0;
       goto out;
     }
     if (c == '\r' || c == '\n') {
       buf[len] = '\0';
       fputc('\n', stdout);
       if (hist) (void)line_history_add(env, hist, buf, len);
       out_rc = (int)len;
       goto out;
     }
     if (c == 4) {
       if (len == 0) {
         buf[0] = '\0';
         out_rc = 0;
         goto out;
       }
       continue;
     }
     if (c == 7) {
       /* Ctrl-G: hand the currently typed line to $EDITOR (seeded with the
        * buffer), then reload whatever was saved. Drop to cooked mode so the
        * editor owns the terminal, then restore raw mode and redraw. */
       uint8_t* edited = NULL;
       size_t edited_size = 0;
       buf[len] = '\0';
       tcsetattr(STDIN_FILENO, TCSAFLUSH, &orig);
       if (driver_edit_temp(env, edit_suffix, (const uint8_t*)buf, len, &edited,
                            &edited_size)) {
         size_t n = edited_size;
         /* Editors append a trailing newline; drop trailing CR/LF so the
          * reloaded prompt stays a single line. */
         while (n > 0 && (edited[n - 1] == '\n' || edited[n - 1] == '\r')) --n;
         if (n >= cap) n = cap - 1u;
         memcpy(buf, edited, n);
         buf[n] = '\0';
         len = n;
         cursor = n;
         have_saved = 0; /* edited text supersedes history navigation */
         hist_pos = hist ? hist->count : 0;
       }
       if (edited) driver_free(env, edited, edited_size);
       tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
       line_redraw(prompt, buf, len, cursor);
       continue;
     }
     if (c == '\t') {
       buf[len] = '\0';
       line_complete(env, buf, cap, &len, &cursor, prompt, complete,
                     complete_user);
       continue;
     }
     if (c == 1) {
       cursor = 0;
       line_redraw(prompt, buf, len, cursor);
       continue;
     }
     if (c == 5) {
       cursor = len;
       line_redraw(prompt, buf, len, cursor);
       continue;
     }
     if (c == 11) {
       buf[cursor] = '\0';
       len = cursor;
       line_redraw(prompt, buf, len, cursor);
       continue;
     }
     if (c == 127 || c == 8) {
       if (cursor == 0) {
         fputc('\a', stdout);
         fflush(stdout);
         continue;
       }
       memmove(buf + cursor - 1u, buf + cursor, len - cursor + 1u);
       --cursor;
       --len;
       line_redraw(prompt, buf, len, cursor);
       continue;
     }
     if (c == 27) {
       unsigned char seq[3];
       ssize_t r1 = read(STDIN_FILENO, seq, 1);
       ssize_t r2 = read(STDIN_FILENO, seq + 1, 1);
       if (r1 != 1 || r2 != 1 || seq[0] != '[') continue;
       if (seq[1] == 'A') {
         if (hist && hist->count > 0 && hist_pos > 0) {
           if (!have_saved) {
             memcpy(saved, buf, len + 1u);
             have_saved = 1;
           }
           --hist_pos;
           line_set(buf, cap, &len, &cursor, hist->items[hist_pos]);
           line_redraw(prompt, buf, len, cursor);
         }
       } else if (seq[1] == 'B') {
         if (hist && have_saved && hist_pos < hist->count) {
           ++hist_pos;
           if (hist_pos == hist->count)
             line_set(buf, cap, &len, &cursor, saved);
           else
             line_set(buf, cap, &len, &cursor, hist->items[hist_pos]);
           line_redraw(prompt, buf, len, cursor);
         }
       } else if (seq[1] == 'C') {
         if (cursor < len) {
           ++cursor;
           line_redraw(prompt, buf, len, cursor);
         }
       } else if (seq[1] == 'D') {
         if (cursor > 0) {
           --cursor;
           line_redraw(prompt, buf, len, cursor);
         }
       } else if (seq[1] == 'H') {
         cursor = 0;
         line_redraw(prompt, buf, len, cursor);
       } else if (seq[1] == 'F') {
         cursor = len;
         line_redraw(prompt, buf, len, cursor);
       } else if (seq[1] >= '1' && seq[1] <= '9') {
         ssize_t r3 = read(STDIN_FILENO, seq + 2, 1);
         if (r3 == 1 && seq[1] == '3' && seq[2] == '~' && cursor < len) {
           memmove(buf + cursor, buf + cursor + 1u, len - cursor);
           --len;
           line_redraw(prompt, buf, len, cursor);
         }
       }
       continue;
     }
     if (c >= 32 && c != 127) {
       if (len + 1u >= cap) {
         fputc('\a', stdout);
         fflush(stdout);
         continue;
       }
       memmove(buf + cursor + 1u, buf + cursor, len - cursor + 1u);
       buf[cursor] = (char)c;
       ++cursor;
       ++len;
       line_redraw(prompt, buf, len, cursor);
     }
   }
 
 out:
   if (raw_enabled) tcsetattr(STDIN_FILENO, TCSAFLUSH, &orig);
   if (saved) driver_free(env, saved, saved_size);
   return out_rc;
 }
 
 /* ---------------- dlsym resolver ---------------- */
 
 void* driver_dlsym_resolver(void* user, KitSlice name_s) {
   /* The linker hands us interned/pool slices that are NUL-terminated, so
    * we can pass .s straight through to the OS-specific os_dlsym. */
   (void)user;
   if (!name_s.s || name_s.len == 0) return NULL;
   return os_dlsym(name_s.s);
 }
 
 /* ---------------- SIGINT handler for the dbg REPL ---------------- */
 
 static void (*s_sigint_cb)(void*);
 static void* s_sigint_cb_user;
 
 static void sigint_trampoline(int sig) {
   (void)sig;
   if (s_sigint_cb) s_sigint_cb(s_sigint_cb_user);
 }
 
 int driver_install_sigint(void (*cb)(void*), void* user) {
   struct sigaction sa;
   s_sigint_cb = cb;
   s_sigint_cb_user = user;
   sa.sa_handler = sigint_trampoline;
   sigemptyset(&sa.sa_mask);
   sa.sa_flags = 0; /* no SA_RESTART: fgetc returns EINTR */
   return sigaction(SIGINT, &sa, NULL) == 0 ? 0 : 1;
 }
 
 void driver_restore_sigint(void) {
   struct sigaction sa;
   s_sigint_cb = NULL;
   s_sigint_cb_user = NULL;
   sa.sa_handler = SIG_DFL;
   sigemptyset(&sa.sa_mask);
   sa.sa_flags = 0;
   sigaction(SIGINT, &sa, NULL);
 }
 
 /* ---------------- host target ---------------- */
 
 static KitArchKind host_arch_self(void) {
 #if defined(__x86_64__)
   return KIT_ARCH_X86_64;
 #elif defined(__aarch64__)
   return KIT_ARCH_ARM_64;
 #elif defined(__arm__)
   return KIT_ARCH_ARM_32;
 #elif defined(__i386__)
   return KIT_ARCH_X86_32;
 #elif defined(__riscv) && (__riscv_xlen == 64)
   return KIT_ARCH_RV64;
 #elif defined(__riscv) && (__riscv_xlen == 32)
   return KIT_ARCH_RV32;
 #elif defined(__wasm__)
   return KIT_ARCH_WASM;
 #else
   return KIT_ARCH_X86_64;
 #endif
 }
 
 KitTargetSpec driver_host_target(void) {
   KitTargetSpec t = {0};
   t.arch = host_arch_self();
   os_host_target_fill(&t);
   t.ptr_size = (uint8_t)sizeof(void*);
   t.ptr_align = (uint8_t)sizeof(void*);
   t.big_endian = 0;
   t.pic = driver_default_pic(t.obj, t.os);
   t.code_model = KIT_CM_DEFAULT;
   return t;
 }
 
 /* ---------------- env wiring (POSIX) ---------------- */
 
 char g_cache_dir[4096];
 
 void driver_env_init(DriverEnv* e) {
   e->heap = &g_heap_libc;
   e->diag = &g_diag_stderr;
   e->file_io.read_all = posix_read_all;
   e->file_io.release = posix_release;
   e->file_io.open_writer = posix_open_writer;
   e->file_io.user = e;
 
   g_execmem_posix.page_size = driver_host_page_size();
   g_execmem_posix.reserve = execmem_reserve;
   g_execmem_posix.protect = execmem_protect;
   g_execmem_posix.release = execmem_release;
   g_execmem_posix.flush_icache = execmem_flush_icache;
   g_execmem_posix.user = NULL;
   e->execmem = &g_execmem_posix;
 
   e->dbg_os = &g_dbg_os_posix;
   /* Opt-in compile metrics (KIT_METRICS): one process-wide profiler backs both
    * the heap counters and libkit's scope timers. NULL when unset -- the metrics
    * hot path is then a single pointer check. */
   e->profiler = driver_metrics_profiler();
 
   {
     const char* xdg = getenv("XDG_CACHE_HOME");
     const char* home = getenv("HOME");
     if (xdg && *xdg) {
       snprintf(g_cache_dir, sizeof(g_cache_dir), "%s/kit", xdg);
     } else if (home && *home) {
       snprintf(g_cache_dir, sizeof(g_cache_dir), "%s/.cache/kit", home);
     } else {
       snprintf(g_cache_dir, sizeof(g_cache_dir), "build/kit-cache");
     }
     e->cache_dir = g_cache_dir;
   }
 
   /* Reproducible-build precedent: SOURCE_DATE_EPOCH wins over wall clock. */
   {
     const char* sde = getenv("SOURCE_DATE_EPOCH");
     if (sde && *sde) {
       char* endp = NULL;
       long long v = strtoll(sde, &endp, 10);
       e->now = (endp != sde && v >= 0) ? (int64_t)v : (int64_t)-1;
     } else {
       time_t t = time(NULL);
       e->now = (t == (time_t)-1) ? (int64_t)-1 : (int64_t)t;
     }
   }
 }
 
 void driver_env_fini(DriverEnv* e) {
   /* Singletons; nothing to release. */
   (void)e;
 }
 
 KitContext driver_env_to_context(const DriverEnv* e) {
   KitContext c;
   c.heap = e->heap;
   c.file_io = &e->file_io;
   c.diag = e->diag;
   c.profiler = e->profiler;
   c.now = e->now;
   return c;
 }
 
 KitJitHost driver_env_to_jit_host(const DriverEnv* e) {
   KitJitHost h;
   h.execmem = e->execmem;
   return h;
 }
 
 KitDbgHost driver_env_to_dbg_host(const DriverEnv* e) {
   KitDbgHost h;
   h.os = e->dbg_os;
   return h;
 }