kit

run.c (39790B)

---

 #include <kit/compile.h>
 #include <kit/core.h>
 #include <kit/interp.h>
 #include <kit/jit.h>
 #include <kit/link.h>
 #include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
 
 #include "backtrace.h"
 #include "cflags.h"
 #include "driver.h"
 #include "hosted.h"
 #include "inputs.h"
 #include "wasm_run.h"
 
 /* `kit run` — JIT-compile one or more inputs and invoke the entry symbol
  * (default `main`) in-process. Args after `--` are passed to the JITed
  * program as argv. Mirrors the cc front-end for input shape (.c / - sources,
  * .o objects, .a archives) and target/diagnostic flag surface; libkit's
  * JIT path forces PIC regardless of `-fPIC`/`-fPIE`/`-mcmodel`.
  *
  * Native host-symbol fallback (so JITed C/object code can call libc) goes
  * through driver_dlsym_resolver in driver/env.c. Wasm source inputs do not get
  * that fallback; host access is controlled by the Wasm import policy. The
  * driver returns whatever the entry returns, or 1 on a compile/link/lookup
  * error. The native entry is invoked as `int(*)(int, char**)`. */
 
 #define RUN_TOOL "run"
 
 typedef struct RunOptions {
   DriverEnv* env;
   KitFrontendRegistry* frontends;
   size_t argv_bound;
 
   int opt_level;
   int no_jit; /* --no-jit: execute the entry via the IR interpreter */
   int debug_info;
   int metrics;
   int bench_time;
   int warnings_are_errors; /* -Werror     */
   uint32_t max_errors;     /* -fmax-errors=N */
   const char* entry;       /* -e, default "main" */
   const char* sysroot;     /* --sysroot   */
   int wants_hosted_libc;   /* -lc         */
   KitTargetSpec target;    /* -target / host */
   DriverTargetFeatures target_features;
   DriverHostedPlan hosted;
 
   DriverCflags cf;
   DriverInputs inputs;
   DriverWasmRunOptions wasm;
 
   char** prog_argv; /* args after `--`     */
   uint32_t prog_argc;
 } RunOptions;
 
 /* `kit run` owns the concrete profiler storage and only formats it after the
  * run completes. Libkit's hot path just updates the arrays in KitProfiler. */
 
 #define RUN_PROFILE_SCOPE_TOTAL \
   ((KitProfileScope)(KIT_PROFILE_SCOPE_EXTERNAL_FIRST + 0u))
 #define RUN_PROFILE_SCOPE_COMPILE_AND_JIT \
   ((KitProfileScope)(KIT_PROFILE_SCOPE_EXTERNAL_FIRST + 1u))
 #define RUN_PROFILE_SCOPE_JIT_LOOKUP \
   ((KitProfileScope)(KIT_PROFILE_SCOPE_EXTERNAL_FIRST + 2u))
 #define RUN_PROFILE_SCOPE_ENTRY_CALL \
   ((KitProfileScope)(KIT_PROFILE_SCOPE_EXTERNAL_FIRST + 3u))
 
 typedef struct RunMetrics {
   KitProfiler profile;
   DriverEnv* env;
 } RunMetrics;
 
 static void run_profile_define_run_scopes(RunMetrics* m) {
   kit_profiler_define_scope(&m->profile, RUN_PROFILE_SCOPE_TOTAL, "run.total");
   kit_profiler_define_scope(&m->profile, RUN_PROFILE_SCOPE_COMPILE_AND_JIT,
                             "run.compile_and_jit");
   kit_profiler_define_scope(&m->profile, RUN_PROFILE_SCOPE_JIT_LOOKUP,
                             "run.jit_lookup");
   kit_profiler_define_scope(&m->profile, RUN_PROFILE_SCOPE_ENTRY_CALL,
                             "run.entry_call");
 }
 
 static void run_metrics_init(RunMetrics* m, DriverEnv* env) {
   kit_profiler_reset(&m->profile);
   m->env = env;
   run_profile_define_run_scopes(m);
 }
 
 static void run_metrics_begin(RunMetrics* m, KitProfileScope scope) {
   if (m) kit_profiler_scope_begin(&m->profile, scope);
 }
 
 static void run_metrics_end(RunMetrics* m, KitProfileScope scope) {
   if (m) kit_profiler_scope_end(&m->profile, scope);
 }
 
 /* Close any still-open scopes, then export aggregate profiler state. */
 static void run_metrics_finish(RunMetrics* m) {
   uint32_t id;
   if (!m) return;
   while (m->profile.depth) {
     KitProfileFrame* f = &m->profile.stack[m->profile.depth - 1u];
     kit_profiler_scope_end(&m->profile, (KitProfileScope)f->id);
   }
   for (id = 1; id < KIT_PROFILE_ID_COUNT; ++id) {
     uint64_t count = m->profile.scope_count[id];
     uint64_t ticks = m->profile.scope_ticks[id];
     if (count) {
       const char* name =
           kit_profiler_scope_name(&m->profile, (KitProfileScope)id);
       if (!name) name = "profile.scope";
       driver_logf("%.*s %llu ticks (%llu calls)",
                   KIT_SLICE_ARG(kit_slice_cstr(name)),
                   (unsigned long long)ticks, (unsigned long long)count);
     }
   }
   for (id = 1; id < KIT_PROFILE_ID_COUNT; ++id) {
     uint64_t value = m->profile.counters[id];
     if (value) {
       const char* name =
           kit_profiler_counter_name(&m->profile, (KitProfileCounter)id);
       if (!name) name = "profile.counter";
       driver_logf("%.*s=%llu", KIT_SLICE_ARG(kit_slice_cstr(name)),
                   (unsigned long long)value);
     }
   }
   if (m->profile.stack_overflow)
     driver_logf("profile.stack_overflow=%u",
                 (unsigned)m->profile.stack_overflow);
   if (m->profile.def_overflow)
     driver_logf("profile.def_overflow=%u", (unsigned)m->profile.def_overflow);
   driver_free(m->env, m, sizeof(*m));
 }
 
 static void run_bench_time(const char* name, uint64_t ns) {
   driver_logf("kit-run %.*s -- %.3f msec", KIT_SLICE_ARG(kit_slice_cstr(name)),
               (double)ns / 1000000.0);
 }
 
 static void run_usage(void) {
   driver_errf(RUN_TOOL, "%.*s",
               KIT_SLICE_ARG(KIT_SLICE_LIT(
                   "usage: kit run [options] inputs... [-- prog-arg...]\n"
                   "       kit run --help    for full option reference")));
 }
 
 void driver_help_run(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit run — JIT-compile inputs and invoke the entry symbol "
           "in-process\n"
           "\n"
           "USAGE\n"
           "  kit run [options] inputs... [-- prog-arg...]\n"
           "\n"
           "DESCRIPTION\n"
           "  Compiles and JIT-links every input, looks up the entry symbol\n"
           "  (default `main`), and calls it as `int(*)(int, char**)`. Args\n"
           "  after `--` are passed to the JITed program as argv. The driver\n"
           "  returns the entry's exit code, or 1 on a compile/link/lookup\n"
           "  error.\n"
           "\n"
           "  Inputs are classified by suffix:\n"
           "    .c .cc .cpp     C source\n"
           "    .wat .wasm      WebAssembly source module\n"
           "    .o .obj         object file\n"
           "    .a              static archive\n"
           "    -               read C source from stdin (single source only)\n"
           "\n"
           "  Native JITed code may call any host symbol resolvable via "
           "dlsym(RTLD_DEFAULT)\n"
           "  — typically libc. Wasm source inputs do not use this fallback.\n"
           "  The JIT path forces PIC; -fPIC / -fPIE / "
           "-mcmodel\n"
           "  are accepted but have no observable effect.\n"
           "\n"
           "COMPILE OPTIONS\n"
           "  -O0 -O1 -O2       Optimization level; -O2 aliases -O1 "
           "(default -O0)\n"
           "  --no-jit          Execute the entry through the IR interpreter\n"
           "                    instead of JIT-compiled native code (forces "
           "-O1\n"
           "                    minimum so the optimizer IR is available)\n"
           "  -g                Emit DWARF debug info\n"
           "  --time, --metrics Emit scoped compile/link/JIT ticks to stderr\n"
           "  --bench-time      Emit parseable compile/JIT/execution timings\n"
           "  -e SYMBOL         Entry symbol (default `main`)\n"
           "  -target TRIPLE    Compile target. Canonical host spellings include\n"
           "                    aarch64-apple-darwin, x86_64-apple-darwin,\n"
           "                    aarch64-linux-gnu, and x86_64-linux-gnu. Native\n"
           "                    in-process execution requires a host-compatible\n"
           "                    architecture/ABI; Wasm uses the sandbox below.\n"
           "  --sysroot DIR     Hosted libc sysroot for headers/defines with "
           "-lc\n"
           "  -lc               Enable hosted libc headers/defines; calls "
           "resolve "
           "via host dlsym\n"
           "  -fPIC -fpic       Position-independent code (no-op for the JIT)\n"
           "  -fPIE -fpie       Position-independent executable (no-op for the "
           "JIT)\n"
           "  -mcmodel=MODEL    small | medium | large (no-op for the JIT)\n"
           "  -Werror           Treat warnings as errors\n"
           "  -fmax-errors=N    Stop after N errors (0 = unlimited)\n"
           "\n"
           "PREPROCESSOR\n"
           "  -I DIR            Add quoted-include search path\n"
           "  -isystem DIR      Add system-include search path\n"
           "  -D NAME[=BODY]    Define a macro\n"
           "  -U NAME           Undefine a builtin/predefined macro\n"
           "\n")));
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "WASM SANDBOX\n"
           "  Wasm inputs run with a deny-by-default host-import policy. "
           "No host\n"
           "  symbol or test-import fallback is enabled unless an explicit "
           "flag\n"
           "  below requests it.\n"
           "  --wasm-memory-max=SIZE\n"
           "                    Maximum total linear-memory reservation "
           "(default 1G)\n"
           "  --wasm-instance-max=SIZE\n"
           "                    Maximum runtime instance size (default 64M)\n"
           "  --wasm-memories-max=N\n"
           "                    Maximum declared linear-memory count\n"
           "  --wasm-imports=deny|wasi|test\n"
           "                    Import resolver policy (default deny). `test` "
           "binds\n"
           "                    only the controlled env.host_add compatibility\n"
           "                    import; it is not a general host-symbol policy.\n"
           "                    `wasi` binds the configured partial WASI "
           "Preview1 "
           "shim.\n"
           "  --wasm-wasi       Alias for --wasm-imports=wasi\n"
           "  --wasm-env=none|allowlist|inherit\n"
           "  --wasm-env-pass=NAME, --wasm-env-set=NAME=VALUE\n"
           "                    Guest environment policy for WASI env imports\n"
           "  --wasm-fs=none    Filesystem disabled (default)\n"
           "  --wasm-map-dir=HOST=GUEST[:ro|rw]\n"
           "  --wasm-map-file=HOST=GUEST[:ro|rw]\n"
           "  --wasm-cwd=GUEST  Guest cwd exposed through the WASI config\n"
           "  --wasm-stdio=null|inherit\n"
           "  --wasm-clock=none|monotonic|realtime\n"
           "  --wasm-random=none|host|seed:HEX\n"
           "                    WASI host-resource policy; default is none\n"
           "\n")));
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "ARGV PASSTHROUGH\n"
           "  --                End of `kit run` options. Tokens after `--` "
           "are\n"
           "                    passed to the JITed program's main(argc, argv)\n"
           "                    starting at argv[1]. argv[0] is synthesized "
           "from\n"
           "                    the first input (path, `<stdin>`, .o, or .a) "
           "so\n"
           "                    JITed code can index argv[0] like a hosted\n"
           "                    program. Without `--` the program receives\n"
           "                    argc==1 with argv[0] set and argv[1]==NULL.\n"
           "  --script FILE     Run FILE as the sole source, passing every\n"
           "                    later token to the program as argv (an "
           "implicit\n"
           "                    `--` after FILE). Implies -lc (hosted libc),\n"
           "                    since scripts are usually hosted; on macOS "
           "that\n"
           "                    still needs --sysroot for header resolution.\n"
           "                    Intended for `#!` script use:\n"
           "                      #!/usr/bin/env -S kit run --script\n"
           "                    Make the .c file executable and run it "
           "directly;\n"
           "                    the kernel appends the path + the user's args.\n"
           "                    Add compile flags before --script, e.g.\n"
           "                      #!/usr/bin/env -S kit run -g --script\n"
           "\n"
           "SOURCE/SDK REQUIREMENTS\n"
           "  Simple JIT source inputs do not need --support-dir. Hosted libc\n"
           "  headers require -lc; on macOS also pass the SDK printed by Kit:\n"
           "    SDK=\"$(kit cc -print-sysroot)\"\n"
           "    kit run -lc --sysroot \"$SDK\" hello.c\n"
           "  Cross sysroots affect preprocessing, but the resulting native code\n"
           "  still must match the current process to execute in-process.\n"
           "\n"
           "GETTING HELP\n"
           "  -h, --help        Show this help and exit\n"
           "  --version         Show Kit version and exit\n"
           "\n"
           "EXAMPLES\n"
           "  kit run hello.c\n"
           "  kit run -O2 -DNDEBUG main.c util.c\n"
           "  SDK=\"$(kit cc -print-sysroot)\"\n"
           "  kit run -lc --sysroot \"$SDK\" hosted.c\n"
           "  kit run main.c -- arg1 arg2\n"
           "  kit run --script script.c arg1 arg2   (as a #! interpreter)\n"
           "\n"
           "EXIT CODES\n"
           "  Returns the exit code of the JITed entry, or 1 on internal "
           "failure.\n"
           "  2 on bad command-line usage.\n")));
 }
 
 static int run_alloc_arrays(RunOptions* o, int argc) {
   size_t bound = (size_t)argc;
   o->argv_bound = bound;
   o->prog_argv = driver_alloc_zeroed(o->env, bound * sizeof(*o->prog_argv));
   if (!o->prog_argv) {
     driver_errf(RUN_TOOL, "out of memory");
     return 1;
   }
   if (driver_inputs_init(&o->inputs, o->env, RUN_TOOL, argc) != 0) return 1;
   o->inputs.frontends = o->frontends;
   if (driver_cflags_init(
           &o->cf, o->env,
           argc + DRIVER_HOSTED_MAX_INCLUDES + DRIVER_HOSTED_MAX_DEFINES) != 0) {
     driver_errf(RUN_TOOL, "out of memory");
     return 1;
   }
   if (driver_target_features_init(&o->target_features, o->env, argc) != 0) {
     driver_errf(RUN_TOOL, "out of memory");
     return 1;
   }
   if (driver_wasm_run_options_init(&o->wasm, o->env, bound) != 0) return 1;
   return 0;
 }
 
 static int run_classify_positional(RunOptions* o, const char* a) {
   int r = driver_inputs_classify(&o->inputs, a);
   if (r < 0) return 1;
   if (r == 0) {
     driver_errf(RUN_TOOL, "input does not have a recognized suffix: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(a)));
     return 1;
   }
   return 0;
 }
 
 static int run_path_is_wasm_source(const char* path) {
   return driver_has_suffix(path, ".wat") || driver_has_suffix(path, ".wasm");
 }
 
 /* Scan raw wasm bytes for a custom section named `want`.
  * On success sets *len_out and returns a pointer into `p`; returns NULL on
  * miss or malformed input. The returned pointer is valid only while `p` is. */
 static const char* wasm_scan_custom(const uint8_t* p, size_t total,
                                     const char* want, uint32_t* len_out) {
   const uint8_t* end = p + total;
   uint8_t id;
   uint32_t size, shift;
   const uint8_t* sec_end;
   if (total < 8) return NULL;
   p += 8; /* skip magic + version */
   while (p < end) {
     uint8_t b;
     id = *p++;
     size = 0;
     shift = 0;
     for (;;) {
       if (p >= end) return NULL;
       b = *p++;
       size |= (uint32_t)(b & 0x7f) << shift;
       if (!(b & 0x80)) break;
       shift += 7;
       if (shift > 28) return NULL;
     }
     if ((uint32_t)(end - p) < size) return NULL;
     sec_end = p + size;
     if (id == 0) {
       uint32_t nlen = 0;
       shift = 0;
       for (;;) {
         if (p >= sec_end) {
           p = sec_end;
           goto next_section;
         }
         b = *p++;
         nlen |= (uint32_t)(b & 0x7f) << shift;
         if (!(b & 0x80)) break;
         shift += 7;
         if (shift > 28) {
           p = sec_end;
           goto next_section;
         }
       }
       if ((uint32_t)(sec_end - p) >= nlen) {
         size_t wlen = driver_strlen(want);
         if (nlen == (uint32_t)wlen && memcmp(p, want, wlen) == 0) {
           p += nlen;
           *len_out = (uint32_t)(sec_end - p);
           return (const char*)p;
         }
       }
     }
   next_section:
     p = sec_end;
   }
   return NULL;
 }
 
 static int run_inputs_have_wasm_source(const DriverInputs* in) {
   uint32_t i;
   for (i = 0; i < in->nsources; ++i)
     if (run_path_is_wasm_source(in->sources[i])) return 1;
   return 0;
 }
 
 static int run_inputs_have_non_wasm(const DriverInputs* in) {
   uint32_t i;
   if (in->nsource_memory || in->nobject_files || in->narchives) return 1;
   for (i = 0; i < in->nsources; ++i)
     if (!run_path_is_wasm_source(in->sources[i])) return 1;
   return 0;
 }
 
 static int run_apply_hosted_profile(RunOptions* o) {
   DriverHostedRequest req;
   uint32_t i;
   if (!o->wants_hosted_libc) return 0;
   {
     DriverHostedRequest z = {0};
     req = z;
   }
   req.env = o->env;
   req.tool = RUN_TOOL;
   req.target = o->target;
   req.sysroot = o->sysroot;
   req.static_link = 0;
   req.link_inputs = 0;
   if (driver_hosted_resolve(&req, &o->hosted) != 0) return 1;
   for (i = 0; i < o->hosted.nsystem_includes; ++i) {
     o->cf.system_include_dirs[o->cf.nsystem_include_dirs++] =
         o->hosted.system_includes[i];
   }
   for (i = 0; i < o->hosted.ndefines; ++i) {
     o->cf.defines[o->cf.ndefines++] = o->hosted.defines[i];
   }
   return 0;
 }
 
 static int run_parse(int argc, char** argv, RunOptions* o) {
   int i;
   int after_dash_dash = 0;
   if (run_alloc_arrays(o, argc) != 0) return 1;
   o->target = driver_host_target();
 
   /* Reserve argv[0] for a synthetic program name filled in below. User
    * args after `--` start at argv[1]. */
   o->prog_argc = 1;
 
   for (i = 1; i < argc; ++i) {
     const char* a = argv[i];
 
     if (after_dash_dash) {
       o->prog_argv[o->prog_argc++] = argv[i];
       continue;
     }
     if (driver_streq(a, "--")) {
       after_dash_dash = 1;
       continue;
     }
     /* `--script FILE`: shebang entry point. The kernel's `#!` mechanism
      * appends the script path and the user's arguments after our flags, with
      * no way to inject a `--` between them. `--script` names the sole source
      * file (the next argv element, supplied by the kernel) and routes every
      * later token — flag-shaped or not — to the program's argv, exactly like
      * an implicit `--` after the script. See driver_help_run / DRIVER.md. */
     if (driver_streq(a, "--script")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "--script requires a source-file argument");
         return 1;
       }
       /* Scripts are overwhelmingly hosted programs, so default `--script` to
        * hosted libc — under the JIT that only enables libc headers/macros
        * (symbols resolve at run time via host dlsym), so the only added cost
        * is needing a sysroot for #include resolution. An earlier explicit
        * -lc is a harmless no-op; this just spares every shebang line from
        * repeating it. */
       o->wants_hosted_libc = 1;
       if (run_classify_positional(o, argv[i]) != 0) return 1;
       after_dash_dash = 1;
       continue;
     }
 
     {
       int wr = driver_wasm_run_try_consume(&o->wasm, RUN_TOOL, argc, argv, &i);
       if (wr < 0) return 1;
       if (wr > 0) continue;
     }
 
     {
       int r =
           driver_cflags_try_consume(&o->cf, o->env, RUN_TOOL, argc, argv, &i);
       if (r < 0) return 1;
       if (r > 0) continue;
     }
 
     if (driver_streq(a, "-g")) {
       o->debug_info = 1;
       continue;
     }
     if (driver_streq(a, "--bench-time")) {
       o->bench_time = 1;
       continue;
     }
     if (driver_streq(a, "--time") || driver_streq(a, "--metrics")) {
       o->metrics = 1;
       continue;
     }
     if (driver_streq(a, "--no-jit")) {
       o->no_jit = 1;
       continue;
     }
     if (driver_streq(a, "-O0")) {
       o->opt_level = 0;
       continue;
     }
     if (driver_streq(a, "-O1")) {
       o->opt_level = 1;
       continue;
     }
     if (driver_streq(a, "-O2")) {
       o->opt_level = 1;
       continue;
     }
 
     if (driver_streq(a, "-Werror")) {
       o->warnings_are_errors = 1;
       continue;
     }
     if (driver_strneq(a, "-fmax-errors=", 13)) {
       uint64_t v;
       if (driver_parse_u64(a + 13, &v) != 0 || v > 0xFFFFFFFFu) {
         driver_errf(RUN_TOOL, "-fmax-errors= requires a non-negative integer");
         return 1;
       }
       o->max_errors = (uint32_t)v;
       continue;
     }
 
     if (driver_streq(a, "-fPIC")) {
       o->target.pic = KIT_PIC_PIC;
       continue;
     }
     if (driver_streq(a, "-fpic")) {
       o->target.pic = KIT_PIC_PIC;
       continue;
     }
     if (driver_streq(a, "-fPIE")) {
       o->target.pic = KIT_PIC_PIE;
       continue;
     }
     if (driver_streq(a, "-fpie")) {
       o->target.pic = KIT_PIC_PIE;
       continue;
     }
 
     if (driver_strneq(a, "-mcmodel=", 9)) {
       if (driver_record_mcmodel(&o->target, RUN_TOOL, a + 9) != 0) return 1;
       continue;
     }
     {
       int tr = driver_target_features_try_consume(&o->target_features, o->env,
                                                   RUN_TOOL, argc, argv, &i);
       if (tr < 0) return 1;
       if (tr > 0) continue;
     }
 
     if (driver_streq(a, "-target")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "-target requires an argument");
         return 1;
       }
       if (driver_target_from_triple(argv[i], &o->target) != 0) {
         driver_err_unknown_target(RUN_TOOL, argv[i]);
         return 1;
       }
       continue;
     }
     if (driver_streq(a, "--sysroot") || driver_streq(a, "-isysroot")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "%.*s requires an argument",
                     KIT_SLICE_ARG(kit_slice_cstr(a)));
         return 1;
       }
       o->sysroot = argv[i];
       continue;
     }
     if (driver_strneq(a, "--sysroot=", 10)) {
       o->sysroot = a + 10;
       continue;
     }
     if (driver_streq(a, "-lc")) {
       o->wants_hosted_libc = 1;
       continue;
     }
     if (driver_streq(a, "-l")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "-l requires an argument");
         return 1;
       }
       if (!driver_streq(argv[i], "c")) {
         driver_errf(RUN_TOOL, "unsupported hosted library for JIT: -l%.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(argv[i])));
         return 1;
       }
       o->wants_hosted_libc = 1;
       continue;
     }
     if (driver_strneq(a, "-l", 2)) {
       if (!driver_streq(a + 2, "c")) {
         driver_errf(RUN_TOOL, "unsupported hosted library for JIT: %.*s",
                     KIT_SLICE_ARG(kit_slice_cstr(a)));
         return 1;
       }
       o->wants_hosted_libc = 1;
       continue;
     }
 
     if (driver_streq(a, "-e")) {
       if (++i >= argc) {
         driver_errf(RUN_TOOL, "-e requires an argument");
         return 1;
       }
       o->entry = argv[i];
       continue;
     }
 
     if (driver_streq(a, "-")) {
       if (run_classify_positional(o, a) != 0) return 1;
       continue;
     }
     if (a[0] == '-' && a[1] != '\0') {
       driver_errf(RUN_TOOL, "unknown flag: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return 1;
     }
 
     if (run_classify_positional(o, a) != 0) return 1;
   }
 
   if (driver_inputs_count(&o->inputs) == 0) {
     driver_errf(RUN_TOOL, "no input files");
     run_usage();
     return 1;
   }
   if (run_inputs_have_wasm_source(&o->inputs) &&
       run_inputs_have_non_wasm(&o->inputs)) {
     driver_errf(RUN_TOOL,
                 "sandboxed wasm run does not support mixed native inputs");
     return 1;
   }
   if (!o->entry && run_inputs_have_wasm_source(&o->inputs) &&
       !run_inputs_have_non_wasm(&o->inputs) && o->inputs.nsources == 1) {
     DriverLoad lf = {0};
     KitSlice bytes = {0};
     if (driver_load_bytes(&o->env->file_io, RUN_TOOL, o->inputs.sources[0], &lf,
                           &bytes) == 0) {
       uint32_t elen = 0;
       const char* ep = wasm_scan_custom((const uint8_t*)bytes.s,
                                         (size_t)bytes.len, "kit-entry", &elen);
       if (ep && elen > 0 && elen < 256) {
         char* buf = (char*)o->env->heap->alloc(o->env->heap, elen + 1u, 1);
         if (buf) {
           memcpy(buf, ep, elen);
           buf[elen] = '\0';
           o->entry = buf;
         }
       }
       driver_release_bytes(&o->env->file_io, &lf);
     }
   }
   if (!o->entry) o->entry = "main";
   if (run_apply_hosted_profile(o) != 0) return 1;
 
   /* Synthetic argv[0]. Hosted programs conventionally read argv[0] as
    * the program name; under `kit run` there is no executable path, so
    * use the first input's display name. */
   o->prog_argv[0] = (char*)driver_inputs_first_name(&o->inputs);
   o->wasm.args = (const char* const*)o->prog_argv;
   o->wasm.nargs = o->prog_argc;
   return 0;
 }
 
 static void run_options_release(RunOptions* o) {
   size_t bound = o->argv_bound;
   driver_hosted_plan_fini(o->env, &o->hosted);
   driver_wasm_run_options_fini(&o->wasm);
   driver_inputs_release(&o->inputs);
   driver_target_features_fini(&o->target_features, o->env);
   driver_cflags_fini(&o->cf, o->env);
   driver_free(o->env, o->prog_argv, bound * sizeof(*o->prog_argv));
   if (o->frontends) kit_frontend_registry_free(o->frontends);
 }
 
 static void run_fill_compile_opts(const RunOptions* o,
                                   KitCCompileOptions* copts) {
   KitCCompileOptions z = {0};
   *copts = z;
   /* The interpreter consumes the O1 PReg-path IR; force at least -O1 so the
    * optimizer runs and each function is captured into the InterpProgram. */
   copts->code.opt_level = (o->no_jit && o->opt_level < 1) ? 1 : o->opt_level;
   copts->code.debug_info = o->debug_info;
   copts->diagnostics.warnings_are_errors = o->warnings_are_errors;
   copts->diagnostics.max_errors = o->max_errors;
 }
 
 /* Compile every C source through the caller-owned compiler, load .o/.a
  * inputs, and JIT-link. On success *out_jit owns the JIT image; caller
  * releases via kit_jit_free. The compiler must outlive the JIT — it
  * backs jit->c, which kit_jit_lookup dereferences. */
 static int run_compile_and_jit(RunOptions* o, KitCompiler* compiler,
                                const KitJitHost* host, KitJit** out_jit) {
   KitCCompileOptions copts;
   KitPreprocessOptions pp;
   void* (*extern_resolver)(void*, KitSlice) = driver_dlsym_resolver;
   run_fill_compile_opts(o, &copts);
   driver_cflags_fill_pp(&o->cf, &pp);
   if (run_inputs_have_wasm_source(&o->inputs) ||
       driver_wasm_run_options_used(&o->wasm))
     extern_resolver = NULL;
   return driver_inputs_compile_and_jit(&o->inputs, compiler, host, &copts, &pp,
                                        o->entry, extern_resolver, NULL,
                                        out_jit);
 }
 
 typedef int (*MainFn)(int, char**);
 
 /* --- crash backtrace ------------------------------------------------------
  * When the JITed program faults, driver_run_with_crash_guard captures the
  * return-address chain (innermost first) inside its fault handler and hands it
  * here; we open the image's DWARF (best effort) and symbolize each frame to
  * stderr. */
 
 typedef struct RunCrashCtx {
   DriverEnv* env;
   KitJit* jit;
   int signo; /* filled in run_on_crash so the caller can derive the exit code */
 } RunCrashCtx;
 
 static void run_bt_emit(void* user, const char* line) {
   (void)user;
   driver_logf("%s", line); /* driver_logf appends the newline */
 }
 
 static void run_on_crash(void* user, int signo, const uint64_t* pcs, int npcs) {
   RunCrashCtx* c = (RunCrashCtx*)user;
   KitContext ctx = driver_env_to_context(c->env);
   KitDebugInfo* dwarf = NULL;
   DriverBtCtx btc;
 
   c->signo = signo;
   driver_logf("kit: program received signal %d; backtrace:", signo);
 
   /* DWARF is best effort: without it we still print addresses + JIT symbols. */
   if (c->jit) {
     const KitObjFile* view = kit_jit_view(c->jit);
     if (view) (void)kit_dwarf_open(&ctx, view, &dwarf);
   }
 
   memset(&btc, 0, sizeof btc);
   btc.jit = c->jit;
   btc.dwarf = dwarf;
   btc.emit = run_bt_emit;
   btc.emit_user = NULL;
   driver_backtrace_print_pcs(&btc, pcs, npcs);
 
   if (dwarf) kit_dwarf_free(dwarf);
 }
 
 /* Host-identity symbol resolver for the interpreter.
  *
  * The interpreter holds symbol names as they appear in the object/image symbol
  * table (already target-mangled, e.g. a leading `_` on Mach-O). kit_jit_lookup
  * only finds GLOBAL-bind symbols, but the toy/C frontends emit module-private
  * data and helper functions with LOCAL bind. So resolve by iterating the JIT
  * image's full symbol table (locals included) for an exact name match — this
  * also avoids the re-mangling kit_jit_lookup would apply. Extern/libc symbols
  * not defined in the image fall back to host dlsym (which wants the unmangled
  * name, so try with a leading `_` stripped too). */
 static void* interp_jit_resolve(void* ctx, KitSlice name) {
   KitJit* jit = (KitJit*)ctx;
   void* p = NULL;
   /* The interpreter holds object-table names (target-mangled, e.g. a leading
    * `_` on Mach-O); the JIT image exposes the canonical unmangled names. Match
    * tolerating a single leading-underscore on either side. */
   KitSlice alt = name;
   if (name.len > 1 && name.s[0] == '_') {
     alt.s = name.s + 1;
     alt.len = name.len - 1;
   }
   /* Two passes so an EXACT name match always wins over the underscore-stripped
    * fallback (avoids a local `_g` masking a global `g`, or vice-versa). */
   int pass;
   for (pass = 0; pass < 2 && !p; ++pass) {
     KitSlice want = (pass == 0) ? name : alt;
     KitJitSymIter* it = NULL;
     if (pass == 1 && alt.s == name.s) break; /* no distinct stripped form */
     if (!jit || kit_jit_sym_iter_new(jit, &it) != KIT_OK) break;
     {
       KitJitSym s;
       while (kit_jit_sym_iter_next(it, &s) == KIT_ITER_ITEM) {
         size_t k;
         if (s.name.len != want.len) continue;
         for (k = 0; k < want.len && s.name.s[k] == want.s[k]; ++k) {
         }
         if (k == want.len) {
           p = (void*)(uintptr_t)s.addr;
           break;
         }
       }
       kit_jit_sym_iter_free(it);
     }
   }
   if (!p) {
     p = driver_dlsym_resolver(NULL, name);
     if (!p && name.s[0] == '_') p = driver_dlsym_resolver(NULL, alt);
   }
   return p;
 }
 
 /* Thread-local resolver for the interpreter. A thread-local symbol resolves to
  * a Mach-O TLV descriptor (whose +16 slot holds the storage) or, on ELF/COFF,
  * directly to the in-image storage; kit_jit_tls_addr normalizes both to the
  * variable's single in-image instance and returns NULL for anything it can't
  * safely resolve (a foreign/extern thread-local resolved through the host). We
  * return NULL in those cases so the engine diagnoses cleanly rather than
  * treating a foreign pointer as the variable's storage. */
 static void* interp_jit_resolve_tls(void* ctx, KitSlice name, int64_t addend) {
   KitJit* jit = (KitJit*)ctx;
   void* sym = interp_jit_resolve(ctx, name);
   void* tls;
   if (!sym) return NULL;
   tls = kit_jit_tls_addr(jit, sym);
   return tls ? (uint8_t*)tls + addend : NULL;
 }
 
 static int run_init_frontends(RunOptions* o, const KitContext* ctx,
                               const KitDriverExtension* ext) {
   if (kit_frontend_registry_new(ctx, &o->frontends) != KIT_OK ||
       kit_frontend_registry_add_builtin(o->frontends) != KIT_OK ||
       (ext && ext->register_frontends &&
        ext->register_frontends(o->frontends) != KIT_OK)) {
     driver_errf(RUN_TOOL, "failed to initialize frontend registry");
     return 1;
   }
   return 0;
 }
 
 int driver_run_ex(int argc, char** argv, const KitDriverExtension* ext) {
   DriverEnv env;
   RunOptions ro = {0};
   KitContext ctx;
   KitJitHost jhost;
   KitTarget* target = NULL;
   KitCompiler* compiler = NULL;
   KitJit* jit = NULL;
   KitInterpProgram* interp = NULL;
   RunMetrics* metrics = NULL;
   void* sym;
   MainFn entry_fn;
   int rc;
   uint64_t bench_total_start = 0;
   uint64_t bench_compile_start = 0;
   uint64_t bench_compile_end = 0;
   uint64_t bench_exec_start = 0;
   uint64_t bench_exec_end = 0;
 
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_run();
     return 0;
   }
 
   driver_env_init(&env);
   ro.env = &env;
   ctx = driver_env_to_context(&env);
 
   if (run_init_frontends(&ro, &ctx, ext) != 0) {
     run_options_release(&ro);
     driver_env_fini(&env);
     return 1;
   }
 
   if (run_parse(argc, argv, &ro) != 0) {
     run_options_release(&ro);
     driver_env_fini(&env);
     return 2;
   }
 
   if (ro.metrics) {
     metrics = driver_alloc_zeroed(&env, sizeof(*metrics));
     if (!metrics) {
       driver_errf(RUN_TOOL, "out of memory");
       run_options_release(&ro);
       driver_env_fini(&env);
       return 1;
     }
     run_metrics_init(metrics, &env);
     env.profiler = &metrics->profile;
     if (ro.metrics && !ro.bench_time) driver_logf("kit metrics:");
     run_metrics_begin(metrics, RUN_PROFILE_SCOPE_TOTAL);
   }
   if (ro.bench_time) bench_total_start = driver_now_ns();
 
   /* Compiler backs the JIT image — keep it alive across kit_jit_lookup
    * and the entry call, free after kit_jit_free. */
   jhost = driver_env_to_jit_host(&env);
   if (driver_target_new(&ctx, ro.target, &ro.target_features, RUN_TOOL,
                         &target) != KIT_OK) {
     driver_errf(RUN_TOOL, "failed to initialize compiler");
     kit_target_free(target);
     run_metrics_finish(metrics);
     run_options_release(&ro);
     driver_env_fini(&env);
     return 1;
   }
   {
     KitCompilerOptions copts;
     memset(&copts, 0, sizeof copts);
     copts.frontends = ro.frontends;
     if (kit_compiler_new_ex(target, &ctx, &copts, &compiler) != KIT_OK) {
       driver_errf(RUN_TOOL, "failed to initialize compiler");
       kit_target_free(target);
       run_metrics_finish(metrics);
       run_options_release(&ro);
       driver_env_fini(&env);
       return 1;
     }
     driver_diag_set_compiler(compiler);
   }
 
   /* For --no-jit, attach an InterpProgram so the optimizer captures each
    * function's IR as it compiles. The native object/JIT image is still built
    * (it lays out data globals and resolves externs/function pointers); only
    * the entry's *execution* is routed through the interpreter. */
   if (ro.no_jit) {
     interp = kit_interp_program_new(compiler);
     if (!interp) {
       driver_errf(RUN_TOOL, "failed to initialize interpreter");
       driver_compiler_free(compiler);
       kit_target_free(target);
       run_metrics_finish(metrics);
       run_options_release(&ro);
       driver_env_fini(&env);
       return 1;
     }
     kit_interp_program_attach(interp, compiler);
   }
 
   if (ro.bench_time) bench_compile_start = driver_now_ns();
   run_metrics_begin(metrics, RUN_PROFILE_SCOPE_COMPILE_AND_JIT);
   rc = run_compile_and_jit(&ro, compiler, &jhost, &jit);
   run_metrics_end(metrics, RUN_PROFILE_SCOPE_COMPILE_AND_JIT);
   if (ro.bench_time) bench_compile_end = driver_now_ns();
   if (rc != 0) {
     if (ro.bench_time)
       run_bench_time("compile_and_jit",
                      bench_compile_end - bench_compile_start);
     kit_interp_program_free(interp);
     driver_compiler_free(compiler);
     kit_target_free(target);
     run_metrics_finish(metrics);
     run_options_release(&ro);
     driver_env_fini(&env);
     return rc;
   }
 
   /* Compile/JIT succeeded; enforce -Werror / note -fmax-errors before running
    * the entry. On a -Werror trip we tear the JIT image down, never executing.
    */
   if (driver_diag_finish(&env, RUN_TOOL, ro.warnings_are_errors,
                          ro.max_errors)) {
     kit_interp_program_free(interp);
     kit_jit_free(jit);
     driver_compiler_free(compiler);
     kit_target_free(target);
     run_metrics_finish(metrics);
     run_options_release(&ro);
     driver_env_fini(&env);
     return 1;
   }
 
   run_metrics_begin(metrics, RUN_PROFILE_SCOPE_JIT_LOOKUP);
   sym = kit_jit_lookup(jit, kit_slice_cstr(ro.entry));
   run_metrics_end(metrics, RUN_PROFILE_SCOPE_JIT_LOOKUP);
   if (!sym) {
     driver_errf(RUN_TOOL, "entry symbol not found: %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(ro.entry)));
     kit_interp_program_free(interp);
     kit_jit_free(jit);
     driver_compiler_free(compiler);
     kit_target_free(target);
     run_metrics_finish(metrics);
     run_options_release(&ro);
     driver_env_fini(&env);
     return 1;
   }
 
   {
     union {
       void* p;
       MainFn fn;
     } u;
     u.p = sym;
     entry_fn = u.fn;
   }
 
   /* --no-jit: execute the entry through the IR interpreter. There is NO JIT
    * fallback — if the entry was not captured as interpretable IR (e.g. it came
    * from a precompiled .o, or uses an unsupported construct), that is an error.
    * The native object/JIT image is still built, but only to lay out data
    * globals and resolve externs/function pointers for the interpreter; the
    * entry's code is never run as native. */
   if (ro.no_jit) {
     KitInterpHost host;
     KitInterpFunc* ifn;
     int64_t ret = 0;
     KitInterpStatus s;
     host.translate = NULL; /* host-identity: abstract addrs are host pointers */
     host.resolve_sym = interp_jit_resolve;
     host.resolve_tls = interp_jit_resolve_tls;
     host.ctx = jit;
     kit_interp_program_set_host(interp, &host);
     /* Wasm modules need their instance/linear-memory set up and a 2-call
      * (init, entry) sequence with the instance pointer as the argument. */
     if (driver_wasm_run_call_entry_interp(&ro.wasm, RUN_TOOL, compiler, jit,
                                           interp, ro.entry, &rc))
       goto after_entry;
     if (driver_wasm_run_options_used(&ro.wasm)) {
       driver_errf(RUN_TOOL, "wasm sandbox flags require a wasm input");
       rc = 1;
       goto after_entry;
     }
     ifn = kit_interp_lookup(interp, kit_slice_cstr(ro.entry));
     if (!ifn) {
       driver_errf(RUN_TOOL,
                   "interp: entry %.*s has no interpretable IR (--no-jit "
                   "requires an IR-compiled entry; .o/.a inputs are not "
                   "supported)",
                   KIT_SLICE_ARG(kit_slice_cstr(ro.entry)));
       rc = 1;
       goto after_entry;
     }
     run_metrics_begin(metrics, RUN_PROFILE_SCOPE_ENTRY_CALL);
     if (ro.bench_time) bench_exec_start = driver_now_ns();
     s = kit_interp_call(interp, ifn, (int)ro.prog_argc, ro.prog_argv, &ret);
     if (ro.bench_time) bench_exec_end = driver_now_ns();
     run_metrics_end(metrics, RUN_PROFILE_SCOPE_ENTRY_CALL);
     if (s == KIT_INTERP_DONE) {
       rc = (int)ret;
     } else {
       /* The engine already emitted an "interp: ... not supported" / trap
        * diagnostic; surface a nonzero status (no native fallback). */
       driver_errf(RUN_TOOL, "interp: could not execute %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(ro.entry)));
       rc = 1;
     }
     goto after_entry;
   }
 
   run_metrics_begin(metrics, RUN_PROFILE_SCOPE_ENTRY_CALL);
   if (ro.bench_time) bench_exec_start = driver_now_ns();
   if (!driver_wasm_run_call_entry(&ro.wasm, RUN_TOOL, compiler, jit, sym,
                                   &rc)) {
     if (driver_wasm_run_options_used(&ro.wasm)) {
       driver_errf(RUN_TOOL, "wasm sandbox flags require a wasm input");
       rc = 1;
     } else {
       RunCrashCtx cc;
       cc.env = &env;
       cc.jit = jit;
       cc.signo = 0;
       if (driver_run_with_crash_guard(&env, ro.target.arch, entry_fn,
                                       (int)ro.prog_argc, ro.prog_argv, &rc,
                                       run_on_crash, &cc))
         rc = 128 + cc.signo; /* program faulted; shell convention */
     }
   }
   if (ro.bench_time) bench_exec_end = driver_now_ns();
   run_metrics_end(metrics, RUN_PROFILE_SCOPE_ENTRY_CALL);
 after_entry:
   if (ro.bench_time) {
     run_bench_time("compile_and_jit", bench_compile_end - bench_compile_start);
     run_bench_time("execution", bench_exec_end - bench_exec_start);
     run_bench_time("total", bench_exec_end - bench_total_start);
   }
 
   kit_interp_program_free(interp);
   kit_jit_free(jit);
   driver_compiler_free(compiler);
   kit_target_free(target);
   run_metrics_finish(metrics);
   run_options_release(&ro);
   driver_env_fini(&env);
   return rc;
 }
 
 int driver_run(int argc, char** argv) { return driver_run_ex(argc, argv, NULL); }