qcc-main.cpp

/*
    qcc-main.cpp

    Qore Code Compiler (qcc) - AOT compiler for Qore

    Qore Programming Language

    Copyright (C) 2003 - 2026 Qore Technologies, s.r.o.

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.

    Note that the Qore library is released under a choice of three open-source
    licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
    information.
*/

#include <qore/Qore.h>
#include <qore/ParseOptionMap.h>
#include "qore/intern/QoreAOT.h"
#include "qore/intern/qore_aot_deps.h"
#include "qore/intern/qore_stdio.h"
#include "qore/intern/QoreAOTExprNodeRegistry.h"
#include "qore/intern/QoreAOTExprSlotRegistry.h"
#include "qore/intern/QoreIR.h"
#include "qore/intern/xxhash.h"
#include "qore/intern/QoreModuleSourceFingerprints.h"

#include <algorithm>
#include <cctype>
#include <cstdio>
#include <cstdint>
#include <cstdlib>
#include <cstring>
#include <cerrno>
#include <dirent.h>
#include <dlfcn.h>
#include <fstream>
#include <limits>
#include <map>
#include <memory>
#include <set>
#include <string>
#include <tuple>
#include <vector>
#include <getopt.h>
#include <sys/stat.h>
#include <utime.h>
#include <unistd.h>
#include <fcntl.h>
#ifdef QORE_QCC_TEST_HOOKS
#include <spawn.h>
#include <sys/wait.h>
extern char** environ;
#endif
#include <zlib.h>
#include <zstd.h>

#include <llvm/Object/Binary.h>
#include <llvm/Object/ObjectFile.h>
#include <llvm/Object/SymbolSize.h>
#include <llvm/Support/Error.h>

static const char* QCC_VERSION = "1.0";
static std::vector<std::pair<std::string, std::string>> file_prefix_maps;

#ifndef QORE_QCC_INSTALL_INCLUDE_DIR
#define QORE_QCC_INSTALL_INCLUDE_DIR ""
#endif

#ifndef QORE_QCC_INSTALL_LIBDIR
#define QORE_QCC_INSTALL_LIBDIR ""
#endif

//! Check if a path is a directory
static bool is_directory(const char* path) {
    struct stat st;
    return (stat(path, &st) == 0 && S_ISDIR(st.st_mode));
}

//! Check if a path is a regular file
static bool is_file(const std::string& path) {
    struct stat st;
    return stat(path.c_str(), &st) == 0 && S_ISREG(st.st_mode);
}

static int64_t file_size(const std::string& path) {
    struct stat st;
    if (stat(path.c_str(), &st) == 0 && S_ISREG(st.st_mode)) {
        return st.st_size;
    }
    return -1;
}

//! True if a path is suitable as a Make depfile prerequisite.
static bool depfile_dependency_exists(const std::string& path) {
    struct stat st;
    return stat(path.c_str(), &st) == 0 && S_ISREG(st.st_mode);
}

static const char* source_mode_suffix(bool include_source) {
    return include_source ? ", include-source" : "";
}

//! Describe what a script aggregate emitted.
/** A declaration-only aggregate lowers no bodies by design, so its variant count is always
    zero; reporting "0 variants" for it reads as a failed build.
 */
static std::string script_aggregate_content_clause(bool native_registers, bool include_source,
        int compiled_count) {
    return QoreAOT::scriptAggregateIsDeclarationOnly(native_registers, include_source)
        ? std::string("declarations only")
        : std::to_string(compiled_count) + " variants";
}

//! Join two path components.
static std::string join_path(const std::string& lhs, const char* rhs) {
    if (lhs.empty()) {
        return rhs;
    }
    if (lhs.back() == '/') {
        return lhs + rhs;
    }
    return lhs + "/" + rhs;
}

//! Return the directory part of a path, or empty when no directory is present.
static std::string dirname_of(const std::string& path) {
    size_t pos = path.find_last_of('/');
    if (pos == std::string::npos) {
        return std::string();
    }
    if (pos == 0) {
        return "/";
    }
    return path.substr(0, pos);
}

//! Add a path once, preserving first-match order.
static void add_unique_path(std::vector<std::string>& paths, const std::string& path) {
    if (path.empty()) {
        return;
    }
    if (std::find(paths.begin(), paths.end(), path) == paths.end()) {
        paths.push_back(path);
    }
}

//! Split Qore-style env path variables.  QORE_INCLUDE_DIR is documented as colon-separated;
//! semicolons are also accepted so CMake-style values work in developer environments.
static void add_env_paths(std::vector<std::string>& paths, const char* env) {
    if (!env || !*env) {
        return;
    }
    const char* start = env;
    for (const char* p = env; ; ++p) {
        if (*p == ':' || *p == ';' || *p == '\0') {
            if (p > start) {
                add_unique_path(paths, std::string(start, p - start));
            }
            if (*p == '\0') {
                break;
            }
            start = p + 1;
        }
    }
}

//! Add an include directory if it contains either public Qore headers or generated headers.
static void add_qore_include_candidate(std::vector<std::string>& dirs, const std::string& dir) {
    if (dir.empty()) {
        return;
    }
    if (is_file(join_path(dir, "qore/Qore.h")) || is_file(join_path(dir, "qore/qore-version.h"))) {
        add_unique_path(dirs, dir);
    }
}

//! Add a library directory if it exists.
static void add_qore_lib_candidate(std::vector<std::string>& dirs, const std::string& dir) {
    if (!dir.empty() && is_directory(dir.c_str())) {
        add_unique_path(dirs, dir);
    }
}

//! Quote one shell argument.
static std::string shell_quote(const std::string& arg) {
    std::string rv("'");
    for (char c : arg) {
        if (c == '\'') {
            rv += "'\\''";
        } else {
            rv.push_back(c);
        }
    }
    rv.push_back('\'');
    return rv;
}

//! Directory containing the loaded libqore.
static std::string get_loaded_libqore_dir() {
    if (QoreEnvironmentValue env_holder("QORE_LIBDIR"); const char* env = env_holder.c_str()) {
        if (*env) {
            return env;
        }
    }

    Dl_info info;
    if (!dladdr(reinterpret_cast<void*>(&qore_init), &info) || !info.dli_fname) {
        return std::string();
    }

    std::string path(info.dli_fname);
    if (!path.empty() && path[0] != '/') {
        char* resolved = realpath(path.c_str(), nullptr);
        if (resolved) {
            path = resolved;
            free(resolved);
        }
    }
    return dirname_of(path);
}

//! Derive qcc link-mode include and library search paths from env, build-tree, install-tree,
//! and the loaded libqore path.  CI runs qcc from the build artifact without a matching
//! system install, so link-mode must not rely on compiler defaults.
static void collect_qcc_link_paths(std::vector<std::string>& include_dirs,
        std::vector<std::string>& lib_dirs) {
    std::vector<std::string> env_include_dirs;
    add_env_paths(env_include_dirs, QoreEnvironmentValue("QORE_INCLUDE_DIRS").c_str());
    add_env_paths(env_include_dirs, QoreEnvironmentValue("QORE_INCLUDE_DIR").c_str());
    for (const auto& dir : env_include_dirs) {
        add_qore_include_candidate(include_dirs, dir);
    }

    const std::string loaded_libdir = get_loaded_libqore_dir();
    add_qore_lib_candidate(lib_dirs, loaded_libdir);
    add_qore_lib_candidate(lib_dirs, QORE_QCC_INSTALL_LIBDIR);

    std::vector<std::string> lib_based_include_dirs;
    if (!loaded_libdir.empty()) {
        lib_based_include_dirs.push_back(join_path(loaded_libdir, "include"));
        std::string parent = dirname_of(loaded_libdir);
        if (!parent.empty()) {
            lib_based_include_dirs.push_back(join_path(parent, "include"));
            std::string grandparent = dirname_of(parent);
            if (!grandparent.empty()) {
                lib_based_include_dirs.push_back(join_path(grandparent, "include"));
            }
        }
    }

    if (!loaded_libdir.empty()) {
        // This two-line file is generated only for development builds and is
        // never installed. Read it here in the standalone compiler, before any
        // user program executes; installed SDKs use the derived paths below.
        std::ifstream paths(join_path(loaded_libdir, "qcc-build-paths.conf"));
        std::string version, source_include;
        if (std::getline(paths, version) && version == "qcc-build-paths-v1"
                && std::getline(paths, source_include) && !source_include.empty()) {
            add_qore_include_candidate(include_dirs, join_path(loaded_libdir, "include"));
            add_qore_include_candidate(include_dirs, source_include[0] == '/' ? source_include
                : join_path(loaded_libdir, source_include.c_str()));
        }
    }
    for (const auto& dir : lib_based_include_dirs) {
        add_qore_include_candidate(include_dirs, dir);
    }
    add_qore_include_candidate(include_dirs, QORE_QCC_INSTALL_INCLUDE_DIR);
}

#ifndef QORE_QCC_SANITIZE_FLAGS
#define QORE_QCC_SANITIZE_FLAGS ""
#endif

//! Add compiler/linker flags for qcc link mode.
/** The sanitizer that libqore was built with, if any, is added as well: its runtime has to be part of the main
    executable, or it is not initialized when libqore starts its threads (a ThreadSanitizer build crashed in the first
    instrumented function of the signal handling thread).  So is the platform version libqore was built for, or the
    linker warns that the executable targets an older macOS than libqore
*/
static void append_qcc_link_flags(std::string& cmd, const std::vector<std::string>& lib_dirs) {
    if (*QORE_QCC_SANITIZE_FLAGS) {
        cmd += " ";
        cmd += QORE_QCC_SANITIZE_FLAGS;
    }
    // the platform version libqore was built for; see QoreAOT::getLinkTargetFlags()
    std::string target_flags = QoreAOT::getLinkTargetFlags();
    if (!target_flags.empty()) {
        cmd += " " + target_flags;
    }
    for (const auto& dir : lib_dirs) {
        cmd += " -L" + shell_quote(dir);
    }
    cmd += " -lqore";
    if (QoreAOT::shouldEmitLinkRPath()) {
        for (const auto& dir : lib_dirs) {
            cmd += " -Xlinker -rpath -Xlinker " + shell_quote(dir);
        }
    }
}

// Phase C Item 2: mirror `QoreAOT::sanitizeCIdentifier` for the
// link-mode glue emission.  Replace every char outside [A-Za-z0-9_]
// with `_` so the file basename becomes a valid C identifier —
// matches the register-fn name qcc -c emits per .qo.
static std::string sanitize_c_identifier(const std::string& s) {
    std::string out;
    out.reserve(s.size());
    for (char c : s) {
        if ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')
                || (c >= '0' && c <= '9') || c == '_') {
            out.push_back(c);
        } else {
            out.push_back('_');
        }
    }
    return out;
}

// Strip directory + extension, returning the file basename suitable
// for use as a C identifier (after sanitize).  `/tmp/foo/bar.qo`
// → `bar`.
static std::string basename_no_ext(const std::string& path) {
    size_t slash = path.find_last_of("/\\");
    std::string name = (slash == std::string::npos) ? path
            : path.substr(slash + 1);
    size_t dot = name.find_last_of('.');
    if (dot != std::string::npos && dot > 0) {
        name = name.substr(0, dot);
    }
    return name;
}

//! Check whether a path ends in a literal extension.
static bool has_extension(const char* path, const char* ext) {
    size_t n = std::strlen(path);
    size_t e = std::strlen(ext);
    return n > e && std::strcmp(path + n - e, ext) == 0;
}

// Check whether a path ends in `.qo`.  Link mode requires every
// positional input to match.
static bool has_qo_extension(const char* path) {
    return has_extension(path, ".qo");
}

//! Initializes the Qore library for qcc itself
/** qcc installs no signal handlers and runs no code that does, so it does not start the signal handling thread:
    SIGINT and SIGTERM keep their default actions, and the thread cannot kill qcc with SIGSYS at shutdown when it is
    run under valgrind.

    This does not change the code qcc compiles: Qore::Option::HAVE_SIGNAL_HANDLING is read in the process the
    compiled code runs in, and marking this process as the compiler makes the \c HAVE_SIGNAL_HANDLING parse define
    follow whether the library supports signal handling, as it did when qcc started the signal handling thread.
    The host main() that qcc generates for an executable initializes the library with signal handling.
*/
static void qcc_init_qore() {
    qore_aot_set_compiler_process();
    qore_init(QL_GPL, "UTF-8", true, QLO_DISABLE_SIGNAL_HANDLING);
}

static bool qcc_check_cancel(const char* operation) {
    // qcc deliberately performs manifest-current checks before qore_init() so
    // no-op builds can skip without starting the Qore runtime.  The normal
    // qore_check_cancel() path needs initialized thread-local Qore state.
    return q_libqore_initalized() && qore_check_cancel(nullptr, operation);
}

// Write a Make-format dependency file at `path`.
// Target (LHS) is `output`; deps are `source` plus, when `context` is
// non-null, every `.qm`/`.qc`/`.ql` under it — the set the parser actually
// opens in `--context=DIR` mode per `compileSeparatedModuleFile`.
// Consumed by cmake's `add_custom_command(... DEPFILE ...)` so sibling-
// file edits in split-module dirs retrigger the affected per-file `.qo`.
// Only spaces and backslashes in paths are escaped — Make handles both.
// Publishes a depfile with a single atomic rename(2).
//
// A depfile is not private to the process that writes it.  The incremental AOT
// scheduler reads every member's depfile to recover the required-edge graph
// that decides component membership, preload closures and publication order,
// and it does so while other members of the same group are compiling.  Writing
// in place truncates the file first, so a concurrent reader could observe an
// empty or partial dependency list -- which is indistinguishable from a source
// that genuinely lost a dependency, and which therefore silently splits or
// merges strongly connected components underneath another builder.  With the
// rename a reader sees either the previous generation or the new one.
//
// The temporary name deliberately does not end in `.d`, so a scan for depfiles
// cannot pick one up mid-write.
static bool write_depfile_atomic(const char* path, const std::string& content) {
    std::string tmp = std::string(path) + ".tmp." + std::to_string(getpid());
    FILE* f = fopen(tmp.c_str(), "w");
    if (!f) {
        fprintf(stderr, "error: --depfile: cannot open '%s' for writing: %s\n",
            tmp.c_str(), strerror(errno));
        return false;
    }
    if (!content.empty()
            && fwrite(content.data(), 1, content.size(), f) != content.size()) {
        int e = errno;
        fclose(f);
        unlink(tmp.c_str());
        fprintf(stderr, "error: --depfile: cannot write '%s': %s\n",
            tmp.c_str(), strerror(e));
        return false;
    }
    if (fclose(f) != 0) {
        int e = errno;
        unlink(tmp.c_str());
        fprintf(stderr, "error: --depfile: cannot close '%s': %s\n",
            tmp.c_str(), strerror(e));
        return false;
    }
    if (rename(tmp.c_str(), path) != 0) {
        int e = errno;
        unlink(tmp.c_str());
        fprintf(stderr, "error: --depfile: cannot replace '%s': %s\n",
            path, strerror(e));
        return false;
    }
    return true;
}

// Writes the depfile of a module compile; for a .qmod (fingerprints true), also the source fingerprint file next to
// it (QoreModuleSourceFingerprints.h): the size, modification time and content hash of each file it lists, with which
// the module loader decides whether a .qmod linked into a source tree is older than its sources by their content
static bool write_depfile(const char* path, const std::string& output,
                          const std::string& source, const char* context,
                          const std::vector<std::string>* extra_deps = nullptr,
                          bool fingerprints = false) {
    // Canonicalize so the relative vs absolute spelling of the same file
    // (e.g. primary passed by qcc as realpath + same file re-emerging
    // from an opendir(context) scan with a relative prefix) dedupes
    // cleanly.  realpath failure falls through to the input spelling.
    auto canon = [](const std::string& s) -> std::string {
        if (s.empty()) {
            return s;
        }
        char* r = realpath(s.c_str(), nullptr);
        if (!r) {
            return s;
        }
        std::string out = r;
        free(r);
        return out;
    };

    std::vector<std::string> deps;
    if (!source.empty()) {
        std::string full = canon(source);
        if (depfile_dependency_exists(full)) {
            deps.push_back(std::move(full));
        }
    }

    if (context) {
        DIR* d = opendir(context);
        if (!d) {
            fprintf(stderr, "error: --depfile: cannot open context dir '%s': %s\n",
                context, strerror(errno));
            return false;
        }
        struct dirent* ent;
        size_t dep_i = 0;
        while ((ent = readdir(d)) != nullptr) {
            if (dep_i && !(dep_i % 100)
                    && qcc_check_cancel("qcc depfile context scan")) {
                fprintf(stderr, "error: operation cancelled during qcc depfile context scan\n");
                closedir(d);
                return false;
            }
            ++dep_i;
            size_t len = strlen(ent->d_name);
            bool keep = false;
            if (len > 3) {
                const char* tail = ent->d_name + len - 3;
                if (!strcmp(tail, ".qm") || !strcmp(tail, ".qc") || !strcmp(tail, ".ql")) {
                    keep = true;
                }
            }
            if (!keep) {
                continue;
            }
            std::string full = canon(std::string(context) + "/" + ent->d_name);
            if (depfile_dependency_exists(full)
                    && std::find(deps.begin(), deps.end(), full) == deps.end()) {
                deps.emplace_back(std::move(full));
            }
        }
        closedir(d);
        std::sort(deps.begin(), deps.end());
    }

    // merge any extra dependency files (e.g. the .qmod files of modules loaded
    // for a compiled module's %requires closure), canonicalized and deduped
    if (extra_deps) {
        for (size_t i = 0; i < extra_deps->size(); ++i) {
            if (i && !(i % 100)
                    && qcc_check_cancel("qcc depfile extra dependency scan")) {
                fprintf(stderr,
                    "error: operation cancelled during qcc depfile extra dependency scan\n");
                return false;
            }
            const std::string& d = (*extra_deps)[i];
            if (d.empty()) {
                continue;
            }
            std::string full = canon(d);
            if (depfile_dependency_exists(full)
                    && std::find(deps.begin(), deps.end(), full) == deps.end()) {
                deps.emplace_back(std::move(full));
            }
        }
    }

    auto escape = [](const std::string& s) {
        std::string out;
        out.reserve(s.size());
        for (char c : s) {
            if (c == ' ' || c == '\\') {
                out += '\\';
            }
            out += c;
        }
        return out;
    };

    std::string content = escape(output);
    content += ':';
    for (const auto& dep : deps) {
        content += " \\\n    ";
        content += escape(dep);
    }
    content += '\n';
    if (!write_depfile_atomic(path, content)) {
        return false;
    }
    if (fingerprints) {
        std::string error;
        if (!qore_aot_write_module_source_fingerprints(path, deps, error)) {
            fprintf(stderr, "error: --depfile: %s\n", error.c_str());
            return false;
        }
    }
    return true;
}

// Write a Make-style depfile from an explicit, already-canonicalized
// dependency list (used by script `-c -L` mode, where compileScriptFile
// reports the exact set of source files it parsed — the target plus its
// `%include` closure — so the build rebuilds the `.qo` when any of them
// changes).
static bool write_depfile_list(const char* path, const std::string& output,
                               const std::vector<std::string>& deps) {
    auto escape = [](const std::string& s) {
        std::string out;
        out.reserve(s.size());
        for (char c : s) {
            if (c == ' ' || c == '\\') {
                out += '\\';
            }
            out += c;
        }
        return out;
    };
    auto canon = [](const std::string& s) -> std::string {
        if (s.empty()) {
            return s;
        }
        char* r = realpath(s.c_str(), nullptr);
        if (!r) {
            return s;
        }
        std::string out = r;
        free(r);
        return out;
    };
    std::string content = escape(output);
    content += ':';
    for (size_t i = 0; i < deps.size(); ++i) {
        if (i && !(i % 100) && qcc_check_cancel("qcc depfile emission")) {
            // Nothing has been published yet, so a cancelled emission leaves the
            // previous depfile in place rather than a truncated one.
            fprintf(stderr, "error: operation cancelled during qcc depfile emission\n");
            return false;
        }
        const std::string& dep = deps[i];
        std::string full = canon(dep);
        if (!depfile_dependency_exists(full)) {
            continue;
        }
        content += " \\\n    ";
        content += escape(full);
    }
    content += '\n';
    return write_depfile_atomic(path, content);
}

// Program options
static const char* output_path = nullptr;
static int opt_level = 3;
// Maximum number of threads that compile the parts of a split module at once (split-after-opt).
// 0 = unset (the CPU count). Propagated to libqore via the QCC_JOBS env var; it never changes the
// output, as a module at or above the split threshold is always split into the same parts.
static int aot_jobs = 0;
static const char* target_triple = nullptr;
static bool static_link = false;
static bool module_mode = false;
// Compile-only mode emits a .qo relocatable object instead of a .qmod.
// Objects can be linked into a generated executable, archived for a C/C++
// host, or aggregated back into a .qmod with qcc -m --from-objects.
static bool compile_only = false;
// --context=DIR passes the owning module directory
// when compiling a single file (`.qm`, `.qc`, or `.ql`) from a split
// module so the parser has the full directory as context while the
// AOT writer emits only the target file's contributions.
static const char* context_dir = nullptr;
// --output-dir=DIR selects the output directory for batch-mode script compile.
// When the user passes multiple positional sources in `-c` script
// mode, qcc parses them all into one QoreProgram (one parse cycle,
// no per-file sibling preload) and emits BASENAME.qo into this dir.
static const char* batch_output_dir = nullptr;
// -L<dir> directories for sibling `.qo` preload
// when compiling a single-file script with `-c` + script context (no
// module wrapper).  Each directory is scanned for `*.qo`; their
// fragment metadata is preloaded into the compile program so the
// target source's cross-file references resolve at parse time.
// Semantically analogous to C's `-L<dir>` for linker library search.
static std::vector<std::string> script_lib_dirs;
// -l/--load=<mod> modules preloaded into the
// compile program before parsing.  Mirrors the runtime-load pattern
// used by Qorus binaries (e.g. qctl_main.cpp req_modules[]) and
// matches `qore -l <mod>` CLI convention.  Types from these modules
// become visible to the parser so sources that reference them
// without %requires directives compile cleanly.  Repeatable;
// loaded in declaration order via MM.parseLoadModule.
static std::vector<std::string> load_modules;
// --stub=<file> declarative-only sources parsed
// into the compile program before target sources.  The host
// synthesizes namespaces, functions, or constants in C++ at runtime
// (e.g. `QoreNamespace* QNS = new QoreNamespace("Qorus")` +
// injection helpers); the stub file mirrors those declarations in
// Qore syntax so the parser can resolve bareword references at
// compile time.  Stubs are NOT emitted as `.qo`s — their per-file
// contributions are excluded because the fragment filter matches
// each target's canonical path, not the stub's path.  Repeatable;
// parsed in declaration order before targets.
static std::vector<std::string> stub_files;
// --define=NAME[=VALUE] preparser defines applied
// via `qpgm->parseDefine()` before any source is parsed.  Mirrors the
// runtime `qpgm->parseDefine(...)` calls emitted by Qorus main.cpp
// files (e.g. `qpgm->parseDefine("NO_ORACLE", true)` in
// exec/qdsp_main.cpp when oracle-datasource-pool is off) so
// AOT-compiled sources honor the same `%ifdef` / `%ifndef` surface
// the runtime sees.  Repeatable; applied in declaration order.
static std::vector<std::string> parse_defines;
// --parse-option=NAME OR's a `PO_*` flag into the
// compile program's parse options.  Mirrors the runtime
// `qpgm->parseSetParseOptions(QORUS_PARSE_OPTIONS)` pattern Qorus
// main.cpp files use to extend the initial `new QoreProgram(po)` set
// (e.g. PO_ALLOW_INJECTION so cross-module `Program::loadApplyTo*`
// calls type-check at parse time).  Without this, methods whose
// `[dom=...]` mask names PO_ALLOW_* report "parse options do not
// allow access" during AOT compile.  Repeatable.
static std::vector<std::string> parse_option_flags;
// --script-aggregate=SYMBOL emits a metadata-only script aggregate object
// with an `init_SYMBOL_qo(QoreProgram*)` registration entry.  It is linked
// alongside the per-file `.qo` objects produced by batch script compilation.
static const char* script_aggregate_symbol = nullptr;
static bool script_aggregate_native_registers = false;
// Batch mode can emit the runtime metadata aggregate from the already parsed
// program, avoiding a second full-source qcc invocation on clean builds.
static const char* batch_script_aggregate_symbol = nullptr;
static const char* batch_script_aggregate_output = nullptr;
static std::vector<std::string> batch_script_aggregate_manifest_inputs;
// --link-qo emits an object-driven aggregate register object from existing
// script-context `.qo` inputs, without reparsing the original sources.
static bool link_qo = false;
static bool strict_call_relocations = false;
static bool allow_unresolved_qo_imports = false;
static const char* link_aggregate_symbol = nullptr;
static const char* qolink_map_path = nullptr;
// --from-objects signals aggregator mode: the
// positional inputs are per-file `.qo` objects (produced by
// `qcc -c --context=DIR <file>`) that get linked together plus a
// freshly-computed metadata glue into the output `.qmod`.  See
// design/aot-object-files-and-module-artifacts.md.
static bool from_objects = false;
// -a / --archive mode.  Combined with --context=DIR
// + positional .qo inputs, produces a `.qoa` static archive (deterministic)
// exposing `qore_qoa_register_all(QoreProgram*)`.  Target use case:
// static linkage into a C++ host (e.g. qorus-core).
static bool archive_mode = false;
static bool include_source = false;
static const char* metadata_compression = nullptr;
static bool verbose = false;
static bool warnings_are_errors = false;
static bool show_help = false;
static bool show_version = false;
static bool dump_info = false;
static bool dump_symbols = false;
static bool dump_sections = false;
static bool dump_index_json = false;

static bool qcc_output_verbose() {
    QoreEnvironmentValue verbose_env_holder("QORE_AOT_VERBOSE");
    const char* verbose_env = verbose_env_holder.c_str();
    return verbose || (verbose_env && *verbose_env && strcmp(verbose_env, "0"))
        || SystemEnvironment::isSet("QORE_AOT_DEBUG");
}

static bool apply_parse_option_flags(QoreParseOptions& po, std::string& error) {
    for (const std::string& raw : parse_option_flags) {
        static const struct {
            const char* name;
            QoreParseOptions value;
        } macro_options[] = {
            {"PO_MODERN",                     PO_MODERN},
            {"PO_NEW_STYLE",                  PO_NEW_STYLE},
            {"PO_REQUIRE_OUR",                PO_REQUIRE_OUR},
            {"PO_REQUIRE_PROTOTYPES",         PO_REQUIRE_PROTOTYPES},
            {"PO_NO_CHILD_PO_RESTRICTIONS",   PO_NO_CHILD_PO_RESTRICTIONS},
            {"PO_ALLOW_INJECTION",            PO_ALLOW_INJECTION},
            {"PO_ALLOW_DEBUGGER",             PO_ALLOW_DEBUGGER},
            {"PO_ALLOW_WEAK_REFERENCES",      PO_ALLOW_WEAK_REFERENCES},
            {"PO_REQUIRE_TYPES",              PO_REQUIRE_TYPES},
            {"PO_STRICT_ARGS",                PO_STRICT_ARGS},
            {"PO_STRONG_ENCAPSULATION",       PO_STRONG_ENCAPSULATION},
            {"PO_ALLOW_BARE_REFS",            PO_ALLOW_BARE_REFS},
            {"PO_ASSUME_LOCAL",               PO_ASSUME_LOCAL},
            {"PO_BROKEN_NARROWED_TYPES",      PO_BROKEN_NARROWED_TYPES},
            {"PO_BROKEN_LIST_PARSING",        PO_BROKEN_LIST_PARSING},
            {"PO_NO_MODULES",                 PO_NO_MODULES},
        };
        bool found = false;
        for (const auto& macro_option : macro_options) {
            if (raw == macro_option.name) {
                po |= macro_option.value;
                found = true;
                break;
            }
        }
        if (found) {
            continue;
        }
        std::string name = raw;
        if (name.rfind("PO_", 0) == 0) {
            name.erase(0, 3);
            std::transform(name.begin(), name.end(), name.begin(), [](unsigned char c) {
                return c == '_' ? '-' : static_cast<char>(std::tolower(c));
            });
        }
        QoreParseOptions opt = ParseOptionMap::find_code(name.c_str());
        if (opt == QoreParseOptions(-1)) {
            error = "unknown --parse-option name: '" + raw + "'";
            return false;
        }
        po |= opt;
    }
    return true;
}
static bool show_targets = false;
// Phase 1 compile-time opt:
static bool strip_debug_info = false;
static const char* time_trace_path = nullptr;
// Phase 5a: OptimizeNone+NoInline for functions exceeding this block count
// (0 = disabled). Trades runtime optimization for dramatic compile-time
// savings on large functions (e.g. HttpServer::handleRequest 905 BBs).
// Default 200 validated on HS (46x compile speedup, ~1-7% runtime cost)
// and SqlUtil (1.70x speedup); OpenApi3 unaffected (no functions >= 200).
static int big_fn_threshold = 200;
// Tracks whether `--big-fn-threshold=N` was explicitly passed on the
// command line.  Needed so the CLI default (200) doesn't silently
// clobber a user-set QORE_AOT_BIG_FN_THRESHOLD env var — getopt can't
// distinguish "user passed --big-fn-threshold=200" from "unset, using
// default 200", so a separate bool carries that intent.
static bool big_fn_threshold_cli_explicit = false;
// --depfile=FILE emits a Make-format dependency
// file after a successful compile, listing every source file the
// target output (re)builds against.  cmake wires it via
// add_custom_command(... DEPFILE ${out}.d) so a touch on any sibling
// `.qc` in a split-dir module's --context=DIR retriggers the
// affected `.qo`.  GCC's `-MMD -MF <path>` pair maps onto this
// single long option.
static const char* depfile_path = nullptr;
// --depfile-target=FILE overrides the Make depfile target.  This is useful
// when build systems track a stamp output while the generated artifact is a
// byproduct.
static const char* depfile_target_path = nullptr;
// --depfile-qo-input-content-stamps rewrites `.qo` entries in explicit depfile
// input lists to the corresponding qcc content stamp.  This lets build systems
// depend on semantic object changes while still passing the real `.qo` files to
// qcc for linking and manifest verification.
static bool depfile_qo_input_content_stamps = false;
// Rewrite source dependencies that are represented completely by imported AOT
// symbol/body contracts to the provider object's semantic compile-contract
// stamp. This avoids recompiling callers after source-only provider edits.
static bool depfile_compile_contract_stamps = false;
// Rewrite the source dependencies that a folded compile-time value or a resolved type left
// behind -- the references that produce no import record, and so cannot be narrowed to a
// compile-contract stamp -- to the provider object's declaration (aggregate) contract stamp.
// Without this they fall through to source-content digests, and a comment-only provider edit
// rebuilds every object that folded any constant from it.
static bool depfile_declaration_contract_stamps = false;
// Optional tab-separated source -> content-digest map supplied by build-system
// integrations. After imported sources have been narrowed to compile-contract
// stamps, remaining source dependencies are rewritten to content-preserving
// sidecars so timestamp-only source changes do not propagate to qcc objects.
static const char* depfile_source_content_map_path = nullptr;
static std::map<std::string, std::string> depfile_source_content_stamps;
enum class DepfileModuleDepsMode {
    Source,
    Artifact,
    None,
};
// Module depfiles default to source prerequisites so their contents do not
// depend on whether a sibling .qmod happened to exist when qcc ran.
static DepfileModuleDepsMode depfile_module_deps_mode = DepfileModuleDepsMode::Source;
// --depfile-dir=DIR emits one Make-format depfile per generated `.qo`
// in batch `-c --output-dir=DIR` mode.  Each depfile basename matches
// the generated object basename with `.d` appended.
static const char* depfile_dir = nullptr;
// Batch mode: emit the standard per-object index/manifest/status/stamp sidecars
// using paths derived from each generated `.qo`.
static bool batch_build_sidecars = false;
// --write-index-json=FILE writes the same build-consumable symbol index JSON as
// --dump-index-json, but as a sidecar next to a generated artifact.
static const char* write_index_json_path = nullptr;
// --write-manifest=FILE writes a deterministic content manifest for generated
// artifacts.  --skip-if-manifest-current uses the same manifest content to
// decide whether qcc can skip a compile/link command without touching outputs.
static const char* write_manifest_path = nullptr;
static bool skip_if_manifest_current = false;
// --write-status-json=FILE writes deterministic build-result metadata for build
// system diagnostics.  --success-stamp=FILE is touched on every successful
// command, including manifest-current skips.  --content-stamp=FILE is created on
// first successful output verification, then touched only when the generated
// output's bytes differ from the previous output.
static const char* write_status_json_path = nullptr;
static const char* success_stamp_path = nullptr;
static const char* content_stamp_path = nullptr;
// Canonical API/value/body contract for consumers that preload this object.
// Unlike the object content stamp, this file changes only when recompiling a
// dependent can change its generated code.
static const char* compile_contract_stamp_path = nullptr;
// Exact declaration contract for declaration-only script aggregates.  It
// retains declarations, signatures, constant values, parse context, and source
// locations while excluding native bodies and runtime registration metadata,
// which remain owned by the linked per-source objects.  Script aggregates can
// therefore depend on this sidecar without reparsing the complete source set
// after an edit that leaves their declaration payload unchanged.
static const char* aggregate_contract_stamp_path = nullptr;
// The body-contract half of the published interface: the hashes --link-qo compares a
// consumer's recorded import against.  Kept apart from the declaration contract so a
// consumer can depend on one without depending on the other.
static const char* body_contract_stamp_path = nullptr;
static const char* declaration_contract_stamp_path = nullptr;

//! Exit status of a -c compile that failed loading or resolving the objects it preloaded with -L
/** Such a failure concerns the preload set the build chose, not the sources compiled -- a parse of the
    whole group preloads nothing and cannot fail this way -- so the build scheduler answers it with that
    parse instead of giving up (see tools/qore-qo-incremental-plan).  Distinct from 75 and 76, which the
    scheduler already uses for a moved source and a moved dependency graph.
*/
static constexpr int QCC_EXIT_PRELOAD_FAILED = 78;
// Extra content dependencies that affect the generated artifact but are not
// necessarily visible to qcc as positional inputs (build context files, generated
// stubs, external tool configuration, etc.).
static std::vector<std::string> manifest_inputs;
// In script `-c -L DIR` mode qcc normally records every preloaded `.qo` from
// `DIR` in the manifest.  Some build systems provide a larger transitive
// preload closure for parse-time declaration loading, while only a smaller
// direct `.qo` set should invalidate the target.  This flag lets such callers
// provide the exact manifest dependencies with --manifest-input.
static bool manifest_skip_qo_library_inputs = false;
// Build-group source-symbol manifest used by script `-c -L DIR` compiles to
// defer local project symbols instead of binding same-name loaded module/stub
// declarations.
static const char* source_symbol_manifest_path = nullptr;

static std::vector<std::string> qcc_depfile_explicit_inputs(
        const std::vector<std::string>& deps) {
    if (!depfile_qo_input_content_stamps) {
        return deps;
    }

    std::vector<std::string> rv;
    rv.reserve(deps.size());
    for (const std::string& dep : deps) {
        if (has_qo_extension(dep.c_str())) {
            rv.push_back(dep + ".content.stamp");
        } else {
            rv.push_back(dep);
        }
    }
    return rv;
}

static const char* depfile_module_deps_mode_name() {
    switch (depfile_module_deps_mode) {
        case DepfileModuleDepsMode::Source:
            return "source";
        case DepfileModuleDepsMode::Artifact:
            return "artifact";
        case DepfileModuleDepsMode::None:
            return "none";
    }
    return "source";
}

static bool has_source_extension(const std::string& path) {
    size_t dot = path.rfind('.');
    if (dot == std::string::npos) {
        return false;
    }
    const std::string ext = path.substr(dot);
    return ext == ".qm" || ext == ".qc" || ext == ".ql";
}

static void add_module_source_dir(const std::string& dir,
        std::vector<std::string>& sources) {
    DIR* d = opendir(dir.c_str());
    if (!d) {
        return;
    }
    std::vector<std::string> found;
    while (dirent* ent = readdir(d)) {
        std::string name = ent->d_name;
        if (name == "." || name == ".." || !has_source_extension(name)) {
            continue;
        }
        std::string path = join_path(dir, name.c_str());
        if (depfile_dependency_exists(path)) {
            found.push_back(std::move(path));
        }
    }
    closedir(d);
    std::sort(found.begin(), found.end());
    sources.insert(sources.end(), found.begin(), found.end());
}

static bool add_module_sources_from_root(const std::string& root,
        const std::string& name, std::vector<std::string>& sources) {
    std::string single = join_path(root, (name + ".qm").c_str());
    if (depfile_dependency_exists(single)) {
        sources.push_back(std::move(single));
        return true;
    }

    std::string split = join_path(root, name.c_str());
    std::string main = join_path(split, (name + ".qm").c_str());
    if (!depfile_dependency_exists(main)) {
        return false;
    }
    add_module_source_dir(split, sources);
    return true;
}

static void append_module_search_paths(std::vector<std::string>& paths,
        const char* path_list) {
    if (!path_list || !*path_list) {
        return;
    }
    const char* begin = path_list;
    for (const char* p = path_list; ; ++p) {
        if (*p != QORE_PATH_SEP && *p) {
            continue;
        }
        if (p != begin) {
            paths.emplace_back(begin, p - begin);
        }
        if (!*p) {
            break;
        }
        begin = p + 1;
    }
}

static std::string module_name_from_path(const std::string& path) {
    size_t slash = path.rfind('/');
    std::string name = slash == std::string::npos ? path : path.substr(slash + 1);
    size_t dot = name.rfind('.');
    if (dot != std::string::npos) {
        name.resize(dot);
    }
    size_t api = name.rfind("-api-");
    if (api != std::string::npos) {
        name.resize(api);
    }
    return name;
}

//! Returns the dependencies of a module compile in the form --depfile-module-deps selects
/** @param resolved_deps the files of the modules loaded, as the module dependency sink recorded them
    @param qmod true for the compile of an AOT module (.qmod): with the source form, the depfile of an AOT module of a
    build tree that is a dependency contributes everything it lists (see qore_aot_set_module_closure_dep_sink());
    the depfile of an object (.qo) keeps the dependencies the incremental object scheduler reads
*/
static std::vector<std::string> qcc_module_depfile_inputs(
        const std::vector<std::string>& resolved_deps, bool qmod = false) {
    if (depfile_module_deps_mode == DepfileModuleDepsMode::Artifact) {
        return resolved_deps;
    }
    if (depfile_module_deps_mode == DepfileModuleDepsMode::None) {
        return {};
    }

    std::vector<std::string> search_paths;
    append_module_search_paths(search_paths, QoreEnvironmentValue("QORE_MODULE_DIR").c_str());
    search_paths.emplace_back(qore_user_module_ver_dir);
    search_paths.emplace_back(qore_module_ver_dir);
    search_paths.emplace_back(qore_user_module_dir);
    search_paths.emplace_back(qore_module_dir);

    std::vector<std::string> sources;
    for (const std::string& dep : resolved_deps) {
        if (has_source_extension(dep)) {
            std::string name = module_name_from_path(dep);
            std::string parent = dirname_of(dep);
            size_t slash = parent.rfind('/');
            std::string parent_name = slash == std::string::npos
                ? parent : parent.substr(slash + 1);
            if (parent_name == name) {
                add_module_source_dir(parent, sources);
            } else {
                sources.push_back(dep);
            }
            continue;
        }

        if (dep.size() < 5 || dep.compare(dep.size() - 5, 5, ".qmod")) {
            // Binary modules and other module artifacts have no Qore source
            // representation that qcc can expand.
            sources.push_back(dep);
            continue;
        }
        // An AOT module of a build tree depends on what its own depfile lists:
        // its sources, the files they include and the modules it requires; a
        // module requiring it depends on all of them, as it sees the module's
        // declarations (see qore_aot_set_module_closure_dep_sink())
        if (qmod) {
            std::vector<std::string> dep_depfile;
            if (qore_aot_read_module_depfile(dep, dep_depfile)) {
                sources.insert(sources.end(), dep_depfile.begin(), dep_depfile.end());
            }
        }
        std::string name = module_name_from_path(dep);
        std::string parent = dirname_of(dep);
        size_t before = sources.size();
        size_t slash = parent.rfind('/');
        std::string parent_name = slash == std::string::npos
            ? parent : parent.substr(slash + 1);
        if (parent_name == name) {
            std::string main = join_path(parent, (name + ".qm").c_str());
            if (depfile_dependency_exists(main)) {
                add_module_source_dir(parent, sources);
            }
        } else {
            add_module_sources_from_root(parent, name, sources);
        }
        if (sources.size() != before) {
            continue;
        }
        for (const std::string& root : search_paths) {
            if (add_module_sources_from_root(root, name, sources)) {
                break;
            }
        }
        if (sources.size() == before) {
            // Preserve a dependency edge when only an installed/generated
            // qmod is available. For in-tree builds the source root is on
            // QORE_MODULE_DIR, so artifact presence does not affect the form.
            sources.push_back(dep);
        }
    }
    std::sort(sources.begin(), sources.end());
    sources.erase(std::unique(sources.begin(), sources.end()), sources.end());
    return sources;
}

// Preserve temporary .qo/glue files generated by one-shot multi-source
// executable mode.  Off by default so failed builds do not leave artifacts
// unless explicitly requested for diagnostics.
static bool save_temps = false;
// Phase C Item 2: --entry=<fn> names the Qore function the emitted
// C++ main() dispatches to after registering every script `.qo`
// input.  Meaningful in explicit object link mode and one-shot
// multi-source executable mode.  Defaults to "main" — hosts that use a
// different convention override via `-e <fn>`.
static const char* entry_fn = "main";

//! returns true if the output of a compile is an AOT module (.qmod), whose depfile gets the source fingerprints
static bool qcc_output_is_qmod(const std::string& output) {
    static constexpr const char ext[] = ".qmod";
    return output.size() > sizeof(ext) - 1 && !output.compare(output.size() - (sizeof(ext) - 1), sizeof(ext) - 1, ext);
}

//! Sets the module dependency sink of a module compile: for an AOT module (.qmod), the one that records everything the
//! module depends on (see qore_aot_set_module_closure_dep_sink()), else the one that records the modules it loads
static void qcc_set_module_dep_sink(std::vector<std::string>* sink, const std::string& output) {
    if (qcc_output_is_qmod(output)) {
        qore_aot_set_module_closure_dep_sink(sink);
    } else {
        qore_aot_set_module_dep_sink(sink);
    }
}

static std::string qcc_depfile_target(const std::string& output) {
    if (depfile_target_path) {
        return depfile_target_path;
    }
    // The module loader uses the depfile of an AOT module only for the module its rule names, and takes a relative
    // target as relative to the depfile's directory, not to the directory qcc ran in: a relative -o made the loader
    // ignore the depfile, so that no source of the module was checked.  The target of a .qmod is therefore its real
    // path (--depfile-target names another one, for a build system that needs it).
    if (qcc_output_is_qmod(output) && !output.empty() && output[0] != '/') {
        char* resolved = realpath(output.c_str(), nullptr);
        if (resolved) {
            std::string rv = resolved;
            free(resolved);
            return rv;
        }
        if (char* cwd = getcwd(nullptr, 0)) {
            std::string rv = std::string(cwd) + "/" + output;
            free(cwd);
            return rv;
        }
    }
    return output;
}

static void print_usage(const char* prog) {
    printf("Qore Code Compiler (qcc) v%s\n", QCC_VERSION);
    printf("Compiles Qore scripts, modules, objects, and archives\n\n");
    printf("Usage: %s [options] <source-file|object...>\n\n", prog);
    printf("Options:\n");
    printf("  -o, --output=FILE      Output file path (default: input name without extension)\n");
    printf("  -O, --opt-level=N      Optimization level 0-3 (default: 3)\n");
    printf("  -m, --module           Compile as module (.qm -> .qmod)\n");
    printf("  -c, --compile-only     Compile to .qo relocatable object\n");
    printf("      --context=DIR      Directory context for per-file .qo compilation\n"
           "                         (parses the full split-module dir but emits only\n"
           "                          the input file's contributions; requires -c)\n");
    printf("  -L DIR                 Script-mode sibling .qo search path.  May be\n"
           "                         repeated.  Each dir is scanned for *.qo; their\n"
           "                         fragment decls are preloaded so cross-file type\n"
           "                         refs in the target source resolve at parse time\n"
           "                         (C-style: .qo ~ .o + .h).  Enables `qcc -c <file>`\n"
           "                         for plain multi-file Qore apps with no .qm.  A\n"
           "                         compile that cannot load or resolve the preloaded\n"
           "                         objects exits with status 78.\n");
    printf("      --output-dir=DIR   Output directory for `-c` compile.  With multiple\n"
           "                         sources (batch mode) this is required and all\n"
           "                         .qo files land in DIR sharing one parse cycle.\n"
           "                         With a single source this is an alternative to\n"
           "                         `-o <file>` — writes <basename>.qo into DIR.\n"
           "                         Mutually exclusive with `-o`.\n");
    printf("  -l, --load=MOD         Load Qore module MOD into the compile program\n"
           "                         before parsing sources.  Use when sources reference\n"
           "                         types from external modules without %%requires\n"
           "                         directives (the host loads the module at runtime).\n"
           "                         May be repeated; modules load in declaration order.\n"
           "                         Matches `qore -l <mod>` CLI convention.\n");
    printf("      --stub=FILE        Preload a declarative Qore source file into the\n"
           "                         compile program before targets — its namespaces,\n"
           "                         typedefs, and constants become visible to the\n"
           "                         parser, but no `.qo` is emitted for the stub.\n"
           "                         Use when the host synthesizes decls in C++ at\n"
           "                         runtime (namespaces, injected functions) that\n"
           "                         target sources reference by bare name.  Repeatable;\n"
           "                         parsed in declaration order before targets.\n");
    printf("      --parse-option=NAME  OR a `PO_*` flag into the compile program's parse\n"
           "                         options (e.g. PO_ALLOW_INJECTION, PO_NO_CHILD_PO_RESTRICTIONS).\n"
           "                         Mirrors the runtime `qpgm->parseSetParseOptions(...)` calls\n"
           "                         Qorus main.cpp files issue so method-domain checks line up\n"
           "                         between AOT and runtime paths.  Repeatable; see the name\n"
           "                         lookup table in QoreAOT.cpp for supported flags.\n");
    printf("      --define=NAME[=VAL]  Set a parser define (NAME=VAL, default VAL=True)\n"
           "                         applied via QoreProgram::parseDefine before any source\n"
           "                         parses.  Mirrors the runtime `qpgm->parseDefine(...)`\n"
           "                         calls Qorus main.cpp files issue so `%%ifdef` /\n"
           "                         `%%ifndef` sections stay in sync between AOT and\n"
           "                         runtime paths (e.g. `--define=NO_ORACLE` excludes\n"
           "                         the oracle-only block in QorusOracleDatasourcePool.qc).\n"
           "                         Repeatable; applied in declaration order.\n");
    printf("      --depfile=FILE     Emit Make-format dependency file at FILE after a\n"
           "                         successful compile.  Lists the output, a colon, and\n"
           "                         every source the parser opens (the target source\n"
           "                         plus, in `--context=DIR` mode, all sibling .qm/.qc/.ql).\n"
           "                         Equivalent to GCC's `-MMD -MF FILE`.  Intended for\n"
           "                         cmake's `add_custom_command(... DEPFILE ...)` so\n"
           "                         incremental builds retrigger on sibling-file edits.\n"
           "                         With --link-qo and --script-aggregate, lists the\n"
           "                         aggregate object's direct input files.  For a .qmod,\n"
           "                         FILE.fingerprints records the size, modification\n"
           "                         time and content hash of each file listed, so that\n"
           "                         the module loader checks a .qmod linked into a source\n"
           "                         tree against the content of its sources.\n");
    printf("      --depfile-target=FILE\n"
           "                         Override the Make depfile target written before the\n"
           "                         colon.  Requires --depfile=FILE and is intended\n"
           "                         for stamp-output custom commands whose generated\n"
           "                         artifact is a byproduct.\n");
    printf("      --depfile-qo-input-content-stamps\n"
           "                         In explicit depfile input lists, record each .qo\n"
           "                         dependency as .qo.content.stamp.  Intended for\n"
           "                         qo-link build rules that already depend on qcc\n"
           "                         content stamps to avoid mtime-only relinks.\n");
    printf("      --depfile-compile-contract-stamps\n"
           "                         Replace source-only AOT import dependencies with\n"
           "                         provider .qo.compile-contract.stamp sidecars so\n"
           "                         comments and non-imported body edits do not\n"
           "                         recompile consumers.\n");
    printf("      --body-contract-stamp=FILE\n"
           "                         Write the body-contract hashes this object\n"
           "                         publishes, which --link-qo compares a consumer's\n"
           "                         recorded import against.  A consumer that baked\n"
           "                         one records it as a dependency, so that a\n"
           "                         provider whose declarations did not change but\n"
           "                         whose bodies did still rebuilds it.\n");
    printf("      --declaration-contract-stamp=FILE\n"
           "                         Write the content-stable contract over the\n"
           "                         declarations the consumers of the generated object\n"
           "                         resolve against: the aggregate contract without\n"
           "                         what only a script aggregate embeds (declaration\n"
           "                         locations and the values of member defaults,\n"
           "                         default arguments and base class arguments)\n");
    printf("      --depfile-declaration-contract-stamps\n"
           "                         Replace the source dependencies left by folded\n"
           "                         compile-time values and resolved types with the\n"
           "                         provider .qo.declaration-contract.stamp sidecar, so a\n"
           "                         provider edit that changes no declaration does not\n"
           "                         recompile the consumers that folded its constants.\n"
           "                         Requires --depfile-source-content-map=FILE.\n");
    printf("      --depfile-source-content-map=FILE\n"
           "                         Rewrite remaining source dependencies using a\n"
           "                         tab-separated source/content-digest map so\n"
           "                         timestamp-only edits do not rebuild objects.\n");
    printf("      --depfile-module-deps=MODE\n"
           "                         Module dependency form: source (default), artifact,\n"
           "                         or none. Source expands split modules to .qm/.qc/.ql.\n");
    printf("      --depfile-dir=DIR  Batch `-c --output-dir` mode only: emit one\n"
           "                         Make-format dependency file per generated `.qo` into\n"
           "                         DIR.  Each depfile is named `<object>.qo.d`.\n");
    printf("      --batch-build-sidecars\n"
           "                         Batch `-c --output-dir` mode only: emit index,\n"
           "                         manifest, status, success-stamp, and content-stamp\n"
           "                         sidecars for every generated `.qo`; requires\n"
           "                         --depfile-dir.\n");
    printf("      --batch-script-aggregate=SYM\n"
           "                         Batch `-c --output-dir` mode: emit a metadata-only\n"
           "                         runtime aggregate from the shared parsed program;\n"
           "                         requires --batch-script-aggregate-output.\n");
    printf("      --batch-script-aggregate-output=FILE\n"
           "                         Output path for --batch-script-aggregate.\n");
    printf("      --batch-script-aggregate-manifest-input=FILE\n"
           "                         Record FILE in the fused aggregate manifest; may\n"
           "                         be repeated for standalone-manifest equivalence.\n");
    printf("      --write-index-json=FILE\n"
           "                         Write build-consumable AOT symbol-index JSON for\n"
           "                         the generated artifact to FILE\n");
    printf("      --write-manifest=FILE\n"
           "                         Write a deterministic content manifest for the\n"
           "                         generated artifact to FILE\n");
    printf("      --manifest-input=FILE\n"
           "                         Add FILE as an extra manifest dependency; may repeat\n");
    printf("      --manifest-skip-qo-library-inputs\n"
           "                         Do not auto-record .qo files found through -L\n"
           "                         preload dirs in the manifest; use --manifest-input\n"
           "                         for the exact content dependencies instead\n");
    printf("      --source-symbol-manifest=FILE\n"
           "                         Script -c mode: defer build-group source symbols\n"
           "                         listed in FILE instead of binding same-name loaded\n"
           "                         module or stub declarations\n");
    printf("      --skip-if-manifest-current\n"
           "                         If --write-manifest matches existing output/input\n"
           "                         content, exit successfully without rebuilding\n");
    printf("      --write-status-json=FILE\n"
           "                         Write deterministic build-result JSON to FILE\n");
    printf("      --success-stamp=FILE\n"
           "                         Touch FILE after a successful compile/link or\n"
           "                         manifest-current skip\n");
    printf("      --content-stamp=FILE\n"
           "                         Create FILE after successful output verification;\n"
           "                         after that, touch it only when output bytes change\n");
    printf("      --compile-contract-stamp=FILE\n"
           "                         Write a content-stable API/value/body contract for\n"
           "                         compile-time consumers of the generated object\n");
    printf("      --aggregate-contract-stamp=FILE\n"
           "                         Write a content-stable contract over all metadata\n"
           "                         consumed by a script aggregate; normalizes only\n"
           "                         the raw source hash in the AOT binary header\n");
    printf("      --save-temps       Keep temporary .qo and glue files generated by\n"
           "                         one-shot multi-source executable mode\n");
    printf("      --script-aggregate=SYM\n"
           "                         Emit one metadata-only script aggregate .qo\n"
           "                         exposing init_SYM_qo(); link it with the\n"
           "                         per-file .qo objects from batch script mode\n");
    printf("      --script-aggregate-native-registers\n"
           "                         With --script-aggregate or --batch-script-aggregate,\n"
           "                         emit calls to linked\n"
           "                         per-file *_script_native_register() entries so\n"
           "                         native bodies are bound from per-file slot maps\n");
    printf("      --link-qo          Link existing script-context .qo objects into\n"
           "                         one aggregate register object without reparsing\n"
           "                         original sources; requires -o and\n"
           "                         --aggregate-symbol=SYM\n");
    printf("      --aggregate-symbol=SYM\n"
           "                         Aggregate symbol tail for --link-qo; emits\n"
           "                         init_SYM_qo(QoreProgram*)\n");
    printf("      --qolink-map=FILE  Write --link-qo map JSON to FILE (default:\n"
           "                         <output>.qolink.json)\n");
    printf("      --strict-call-relocations\n"
           "                         With --link-qo, fail if any call relocation is\n"
           "                         unresolved, ambiguous, or hash-mismatched.\n"
           "                         Useful for complete closed-world test links;\n"
           "                         production links can keep optional runtime fallback.\n");
    printf("      --allow-unresolved-imports\n"
           "                         With --link-qo, permit required symbol imports to\n"
           "                         remain unresolved in this aggregate and record them\n"
           "                         in the link map. Intended only for intermediate\n"
           "                         partial aggregates that are checked later by a\n"
           "                         complete strict link.\n");
    printf("      --from-objects     Aggregate mode: positional args are per-file .qo\n"
           "                         inputs; requires -m and --context=DIR; produces a\n"
           "                         standard .qmod by linking the .qo's + fresh glue\n");
    printf("  -a, --archive          Archive mode: positional args are per-file .qo inputs;\n"
           "                         requires --context=DIR; produces a .qoa static archive\n"
           "                         exposing qore_qoa_register_all() for a C++ host\n");
    printf("  -S, --static           Link single-source executables statically against libqore\n");
    printf("  -t, --target=TRIPLE    Target triple for cross-compilation\n");
    printf("      --show-targets     Show supported target architectures and quit\n");
    printf("      --include-source   Embed source text in AOT metadata\n");
    printf("      --strip-source     Strip source text (default)\n");
    printf("      --aot-metadata-compression=MODE\n"
           "                         Metadata compression policy: auto, none, zlib, zstd,\n"
           "                         sectioned\n"
           "                         (default: auto)\n");
    printf("      --file-prefix-map=OLD=NEW\n"
           "                         Map emitted source paths in a final executable or\n"
           "                         whole module; last matching prefix wins. OLD also\n"
           "                         matches the canonical form of the path it names.\n"
           "                         Input files and depfiles keep physical paths. Not\n"
           "                         for incremental .qo or object-link modes.\n");
    printf("      --strip-debug-info Strip DWARF debug info (faster compile, no debugger)\n");
    printf("  -g                     Emit DWARF debug info (default)\n");
    printf("      --time-trace[=PATH]  Emit Chrome-format trace of opt+codegen passes\n");
    printf("                         (default PATH: qcc.trace.json; view at chrome://tracing)\n");
    printf("      --big-fn-threshold=N  Mark functions >= N IR blocks as OptimizeNone+NoInline\n");
    printf("                         (trades ~1-7%% runtime for up to 46x compile speedup;\n");
    printf("                         default: 200; 0 = off)\n");
    printf("      --jobs=N           Parallel backend codegen threads for the parts of a\n");
    printf("                         split module (default: CPU count; throttled by the make\n");
    printf("                         jobserver; does not change the output)\n");
    printf("  -e, --entry=FN         Qore function the emitted C++ main() calls after\n"
           "                         registering script objects (default: main).\n"
           "                         Applies to one-shot multi-source mode and\n"
           "                         `.qo` link mode.\n");
    printf("  -r, --warnings-are-errors\n"
           "                         Treat Qore parser warnings as fatal compile errors\n");
    printf("  -v, --verbose          Verbose output\n");
    printf("  -h, --help             Show this help message\n");
    printf("  -V, --version          Show version information\n");
    printf("      --dump-info        Inspect embedded Qore AOT metadata in object files,\n"
           "                         .qmod modules, .qo fragments, .qoa archives, or\n"
           "                         linked AOT executables without executing them\n");
    printf("      --dump-symbols     Include an nm-like symbol table view\n");
    printf("      --dump-sections    Include object and AOT section tables\n");
    printf("      --dump-index-json  Emit build-consumable AOT symbol-index JSON\n");
    printf("\n");
    printf("Examples:\n");
    printf("  %s script.qr                   # Compile to 'script' executable\n", prog);
    printf("  %s -o myapp script.qr          # Compile to 'myapp' executable\n", prog);
    printf("  %s -o myapp lib.qr main.qr     # One-shot multi-source executable\n", prog);
    printf("  %s -c --output-dir=aot lib.qr main.qr  # Batch-compile app sources\n", prog);
    printf("  %s -o myapp aot/*.qo           # Link compiled app objects\n", prog);
    printf("  %s -o myapp main.qo lib.qo     # Link-mode: .qo's -> 'myapp' binary\n", prog);
    printf("  %s -m MyModule.qm              # Compile single-file module to 'MyModule.qmod'\n", prog);
    printf("  %s -m qlib/DataProvider        # Compile split module directory\n", prog);
    printf("  %s -S -o myapp script.qr       # Static link (no libqore.so dependency)\n", prog);
    printf("\n");
    printf("Notes:\n");
    printf("  - AOT requires %%modern: all PO_MODERN options (PO_ALLOW_BARE_REFS, PO_ASSUME_LOCAL,\n");
    printf("    PO_REQUIRE_TYPES, PO_STRICT_ARGS, PO_STRONG_ENCAPSULATION) must be set once the source\n");
    printf("    is parsed, or the input is rejected; .qr and other non-.q source extensions enable\n");
    printf("    %%modern by default, .q remains legacy unless the source contains %%modern\n");
    printf("  - Static linking requires libqore_static.a (build with -DBUILD_STATIC_LIBQORE=ON)\n");
    printf("  - Cross-compilation requires LLVM support for the target architecture\n");
}

static void print_version() {
    printf("qcc (Qore Code Compiler) v%s\n", QCC_VERSION);
    printf("Using Qore library v%s\n", qore_version_string);
    printf("AOT runtime identity: %s\n", qore_aot_runtime_identity);
    printf("Built with LLVM for JIT/AOT compilation\n");
#ifdef QORE_QCC_TEST_HOOKS
    // the tests that need them skip without them (see QORE_QCC_TEST_HOOKS in CMakeLists.txt)
    printf("Test hooks: enabled\n");
#endif
}

static bool qccHandleWarnings(ExceptionSink& wsink) {
    bool has_warnings = wsink.isException();
    wsink.handleWarnings();
    if (!has_warnings || !warnings_are_errors) {
        return false;
    }
    fprintf(stderr, "error: Qore parser warnings treated as fatal compile errors\n");
    return true;
}

static struct option long_options[] = {
    {"output",            required_argument, nullptr, 'o'},
    {"opt-level",         required_argument, nullptr, 'O'},
    {"module",            no_argument,       nullptr, 'm'},
    {"compile-only",      no_argument,       nullptr, 'c'},
    {"static",            no_argument,       nullptr, 'S'},
    {"target",            required_argument, nullptr, 't'},
    {"show-targets",      no_argument,       nullptr, 'T'},
    {"include-source",    no_argument,       nullptr, 'I'},
    {"strip-source",      no_argument,       nullptr, 'P'},
    {"strip-debug-info",  no_argument,       nullptr, 'D'},
    {"time-trace",        optional_argument, nullptr, 'Y'},
    {"big-fn-threshold",  required_argument, nullptr, 'B'},
    {"context",           required_argument, nullptr, 'C'},
    {"library-path",      required_argument, nullptr, 'L'},
    {"load",              required_argument, nullptr, 'l'},
    // long-only options (no short form): use values > 255 so they
    // don't collide with char short codes.
    {"output-dir",        required_argument, nullptr, 0x100},
    {"stub",              required_argument, nullptr, 0x101},
    {"depfile",           required_argument, nullptr, 0x102},
    {"define",            required_argument, nullptr, 0x103},
    {"parse-option",      required_argument, nullptr, 0x104},
    {"dump-info",         no_argument,       nullptr, 0x105},
    {"dump-symbols",      no_argument,       nullptr, 0x106},
    {"dump-sections",     no_argument,       nullptr, 0x107},
    {"save-temps",        no_argument,       nullptr, 0x108},
    {"aot-metadata-compression", required_argument, nullptr, 0x109},
    {"script-aggregate",  required_argument, nullptr, 0x10a},
    {"depfile-dir",       required_argument, nullptr, 0x10b},
    {"dump-index-json",   no_argument,       nullptr, 0x10c},
    {"link-qo",           no_argument,       nullptr, 0x10d},
    {"aggregate-symbol",  required_argument, nullptr, 0x10e},
    {"qolink-map",        required_argument, nullptr, 0x10f},
    {"strict-call-relocations", no_argument, nullptr, 0x110},
    {"script-aggregate-native-registers", no_argument, nullptr, 0x111},
    {"allow-unresolved-imports", no_argument, nullptr, 0x112},
    {"write-index-json",  required_argument, nullptr, 0x113},
    {"write-manifest",    required_argument, nullptr, 0x114},
    {"skip-if-manifest-current", no_argument, nullptr, 0x115},
    {"manifest-input",    required_argument, nullptr, 0x116},
    {"write-status-json", required_argument, nullptr, 0x117},
    {"success-stamp",     required_argument, nullptr, 0x118},
    {"content-stamp",     required_argument, nullptr, 0x119},
    {"manifest-skip-qo-library-inputs", no_argument, nullptr, 0x11a},
    {"depfile-target",    required_argument, nullptr, 0x11b},
    {"depfile-qo-input-content-stamps", no_argument, nullptr, 0x11c},
    {"source-symbol-manifest", required_argument, nullptr, 0x11d},
    {"jobs",              required_argument, nullptr, 0x11e},
    {"batch-build-sidecars", no_argument,   nullptr, 0x11f},
    {"depfile-module-deps", required_argument, nullptr, 0x120},
    {"compile-contract-stamp", required_argument, nullptr, 0x121},
    {"depfile-compile-contract-stamps", no_argument, nullptr, 0x122},
    {"batch-script-aggregate", required_argument, nullptr, 0x123},
    {"batch-script-aggregate-output", required_argument, nullptr, 0x124},
    {"batch-script-aggregate-manifest-input", required_argument, nullptr, 0x125},
    {"depfile-source-content-map", required_argument, nullptr, 0x126},
    {"aggregate-contract-stamp", required_argument, nullptr, 0x127},
    {"depfile-declaration-contract-stamps", no_argument, nullptr, 0x128},
    {"body-contract-stamp", required_argument, nullptr, 0x129},
    {"file-prefix-map", required_argument, nullptr, 0x12a},
    {"declaration-contract-stamp", required_argument, nullptr, 0x12b},
    {"from-objects",      no_argument,       nullptr, 'F'},
    {"archive",           no_argument,       nullptr, 'a'},
    {"entry",             required_argument, nullptr, 'e'},
    {"warnings-are-errors", no_argument,     nullptr, 'r'},
    {"verbose",           no_argument,       nullptr, 'v'},
    {"help",              no_argument,       nullptr, 'h'},
    {"version",           no_argument,       nullptr, 'V'},
    {nullptr,             0,                 nullptr, 0}
};

static int parse_options_cmdline(int argc, char** argv) {
    int opt;
    while ((opt = getopt_long(argc, argv, "o:O:mcSt:TL:l:age:rvhV", long_options, nullptr)) != -1) {
        switch (opt) {
            case 0x12a: {  // --file-prefix-map
                const std::string map(optarg);
                const size_t separator = map.rfind('=');
                if (separator == std::string::npos || !separator) {
                    fprintf(stderr, "error: --file-prefix-map requires OLD=NEW with a nonempty OLD prefix\n");
                    return 1;
                }
                file_prefix_maps.emplace_back(map.substr(0, separator), map.substr(separator + 1));
                break;
            }
            case 'o':
                output_path = optarg;
                break;
            case 'O':
                opt_level = atoi(optarg);
                if (opt_level < 0 || opt_level > 3) {
                    fprintf(stderr, "error: invalid optimization level '%s' (must be 0-3)\n", optarg);
                    return 1;
                }
                break;
            case 'm':
                module_mode = true;
                break;
            case 'c':
                compile_only = true;
                break;
            case 'S':
                static_link = true;
                break;
            case 't':
                target_triple = optarg;
                break;
            case 'T':
                show_targets = true;
                break;
            case 'I':
                include_source = true;
                break;
            case 'P':
                // strip-source is the default; this is a no-op for backward compatibility
                include_source = false;
                break;
            case 'D':
                strip_debug_info = true;
                break;
            case 'g':
                // -g: explicitly request debug info (default, but overrides --strip-debug-info
                // when both given)
                strip_debug_info = false;
                break;
            case 'Y':
                time_trace_path = optarg ? optarg : "qcc.trace.json";
                break;
            case 'B':
                big_fn_threshold = atoi(optarg);
                if (big_fn_threshold < 0) {
                    fprintf(stderr, "error: --big-fn-threshold must be >= 0\n");
                    return 1;
                }
                big_fn_threshold_cli_explicit = true;
                break;
            case 'C':
                context_dir = optarg;
                break;
            case 'L':
                script_lib_dirs.emplace_back(optarg);
                break;
            case 'l':
                load_modules.emplace_back(optarg);
                break;
            case 0x100:  // --output-dir
                batch_output_dir = optarg;
                break;
            case 0x101:  // --stub
                stub_files.emplace_back(optarg);
                break;
            case 0x102:  // --depfile
                depfile_path = optarg;
                break;
            case 0x11b:  // --depfile-target
                depfile_target_path = optarg;
                break;
            case 0x10b:  // --depfile-dir
                depfile_dir = optarg;
                break;
            case 0x103:  // --define
                parse_defines.emplace_back(optarg);
                break;
            case 0x104:  // --parse-option
                parse_option_flags.emplace_back(optarg);
                break;
            case 0x105:  // --dump-info
                dump_info = true;
                break;
            case 0x106:  // --dump-symbols
                dump_symbols = true;
                break;
            case 0x107:  // --dump-sections
                dump_sections = true;
                break;
            case 0x10c:  // --dump-index-json
                dump_index_json = true;
                break;
            case 0x108:  // --save-temps
                save_temps = true;
                break;
            case 0x109:  // --aot-metadata-compression
                if (strcmp(optarg, "auto") && strcmp(optarg, "none")
                        && strcmp(optarg, "zlib") && strcmp(optarg, "zstd")
                        && strcmp(optarg, "sectioned")) {
                    fprintf(stderr, "error: invalid --aot-metadata-compression value '%s' "
                        "(must be auto, none, zlib, zstd, or sectioned)\n", optarg);
                    return 1;
                }
                metadata_compression = optarg;
                break;
            case 0x10a:  // --script-aggregate
                script_aggregate_symbol = optarg;
                break;
            case 0x10d:  // --link-qo
                link_qo = true;
                break;
            case 0x10e:  // --aggregate-symbol
                link_aggregate_symbol = optarg;
                break;
            case 0x10f:  // --qolink-map
                qolink_map_path = optarg;
                break;
            case 0x110:  // --strict-call-relocations
                strict_call_relocations = true;
                break;
            case 0x111:  // --script-aggregate-native-registers
                script_aggregate_native_registers = true;
                break;
            case 0x112:  // --allow-unresolved-imports
                allow_unresolved_qo_imports = true;
                break;
            case 0x113:  // --write-index-json
                write_index_json_path = optarg;
                break;
            case 0x114:  // --write-manifest
                write_manifest_path = optarg;
                break;
            case 0x115:  // --skip-if-manifest-current
                skip_if_manifest_current = true;
                break;
            case 0x116:  // --manifest-input
                manifest_inputs.emplace_back(optarg);
                break;
            case 0x117:  // --write-status-json
                write_status_json_path = optarg;
                break;
            case 0x118:  // --success-stamp
                success_stamp_path = optarg;
                break;
            case 0x119:  // --content-stamp
                content_stamp_path = optarg;
                break;
            case 0x11a:  // --manifest-skip-qo-library-inputs
                manifest_skip_qo_library_inputs = true;
                break;
            case 0x11c:  // --depfile-qo-input-content-stamps
                depfile_qo_input_content_stamps = true;
                break;
            case 0x11d:  // --source-symbol-manifest
                source_symbol_manifest_path = optarg;
                manifest_inputs.emplace_back(optarg);
                break;
            case 0x11e:  // --jobs
                aot_jobs = atoi(optarg);
                if (aot_jobs < 1) {
                    fprintf(stderr, "error: --jobs must be >= 1\n");
                    return -1;
                }
                break;
            case 0x11f:  // --batch-build-sidecars
                batch_build_sidecars = true;
                break;
            case 0x120:  // --depfile-module-deps
                if (!strcmp(optarg, "source")) {
                    depfile_module_deps_mode = DepfileModuleDepsMode::Source;
                } else if (!strcmp(optarg, "artifact")) {
                    depfile_module_deps_mode = DepfileModuleDepsMode::Artifact;
                } else if (!strcmp(optarg, "none")) {
                    depfile_module_deps_mode = DepfileModuleDepsMode::None;
                } else {
                    fprintf(stderr, "error: invalid --depfile-module-deps value '%s' "
                        "(must be source, artifact, or none)\n", optarg);
                    return 1;
                }
                break;
            case 0x121:  // --compile-contract-stamp
                compile_contract_stamp_path = optarg;
                break;
            case 0x122:  // --depfile-compile-contract-stamps
                depfile_compile_contract_stamps = true;
                break;
            case 0x123:  // --batch-script-aggregate
                batch_script_aggregate_symbol = optarg;
                break;
            case 0x124:  // --batch-script-aggregate-output
                batch_script_aggregate_output = optarg;
                break;
            case 0x125:  // --batch-script-aggregate-manifest-input
                batch_script_aggregate_manifest_inputs.emplace_back(optarg);
                break;
            case 0x126:  // --depfile-source-content-map
                depfile_source_content_map_path = optarg;
                break;
            case 0x127:  // --aggregate-contract-stamp
                aggregate_contract_stamp_path = optarg;
                break;
            case 0x128:  // --depfile-declaration-contract-stamps
                depfile_declaration_contract_stamps = true;
                break;
            case 0x129:  // --body-contract-stamp
                body_contract_stamp_path = optarg;
                break;
            case 0x12b:  // --declaration-contract-stamp
                declaration_contract_stamp_path = optarg;
                break;
            case 'F':
                from_objects = true;
                break;
            case 'a':
                archive_mode = true;
                break;
            case 'e':
                entry_fn = optarg;
                break;
            case 'r':
                warnings_are_errors = true;
                break;
            case 'v':
                verbose = true;
                break;
            case 'h':
                show_help = true;
                break;
            case 'V':
                show_version = true;
                break;
            default:
                return 1;
        }
    }
    return 0;
}

static bool read_file(const char* path, std::string& content) {
    FILE* f = fopen(path, "rb");
    if (!f) {
        fprintf(stderr, "error: cannot open '%s': %s\n", path, strerror(errno));
        return false;
    }

    if (fseek(f, 0, SEEK_END) != 0) {
        fprintf(stderr, "error: cannot seek '%s': %s\n", path, strerror(errno));
        fclose(f);
        return false;
    }

    long fsize = ftell(f);
    if (fsize < 0) {
        fprintf(stderr, "error: cannot get size of '%s': %s\n", path, strerror(errno));
        fclose(f);
        return false;
    }

    if (fseek(f, 0, SEEK_SET) != 0) {
        fprintf(stderr, "error: cannot seek '%s': %s\n", path, strerror(errno));
        fclose(f);
        return false;
    }

    if (!fsize) {
        content.clear();
        if (fclose(f) != 0) {
            fprintf(stderr, "error: cannot close '%s': %s\n", path, strerror(errno));
            return false;
        }
        return true;
    }

    size_t expected = static_cast<size_t>(fsize);
    content.resize(expected);
    size_t nread = fread(&content[0], 1, expected, f);
    if (nread != expected) {
        if (ferror(f)) {
            fprintf(stderr, "error: cannot read '%s': %s\n", path, strerror(errno));
        } else {
            fprintf(stderr, "error: short read from '%s': expected %zu bytes, got %zu\n",
                path, expected, nread);
        }
        fclose(f);
        content.clear();
        return false;
    }
    if (fclose(f) != 0) {
        fprintf(stderr, "error: cannot close '%s': %s\n", path, strerror(errno));
        content.clear();
        return false;
    }

    return true;
}

struct AOTDumpMetadataBlob {
    std::string source;
    std::vector<uint8_t> bytes;
};

static uint16_t read_u16_le(const uint8_t* p) {
    return static_cast<uint16_t>(p[0])
        | (static_cast<uint16_t>(p[1]) << 8);
}

static uint32_t read_u32_le(const uint8_t* p) {
    return static_cast<uint32_t>(p[0])
        | (static_cast<uint32_t>(p[1]) << 8)
        | (static_cast<uint32_t>(p[2]) << 16)
        | (static_cast<uint32_t>(p[3]) << 24);
}

static bool find_aot_metadata_length(const uint8_t* data, size_t avail, size_t& len) {
    len = 0;
    if (avail < QORE_AOT_HEADER_SIZE) {
        return false;
    }
    if (read_u32_le(data) != QORE_AOT_BINARY_MAGIC) {
        return false;
    }
    uint16_t version = read_u16_le(data + 4);
    if (version == 0 || version > QORE_AOT_BINARY_VERSION) {
        return false;
    }

    uint8_t compression = data[34];
    if (compression == QORE_AOT_COMPRESSION_NONE
            || compression == QORE_AOT_COMPRESSION_SECTIONED_ZSTD) {
        uint32_t section_count = read_u32_le(data + 16);
        if (section_count > 100000) {
            return false;
        }
        constexpr size_t section_header_size = 12;
        size_t section_dir_size = static_cast<size_t>(section_count) * section_header_size;
        size_t string_pool_size_pos = QORE_AOT_HEADER_SIZE + section_dir_size;
        if (string_pool_size_pos + 4 > avail) {
            return false;
        }
        uint32_t string_pool_size = read_u32_le(data + string_pool_size_pos);
        size_t data_area_offset = string_pool_size_pos + 4 + string_pool_size;
        if (data_area_offset > avail) {
            return false;
        }

        uint64_t data_area_size = 0;
        const uint8_t* sec = data + QORE_AOT_HEADER_SIZE;
        for (uint32_t i = 0; i < section_count; ++i, sec += section_header_size) {
            if (i && !(i % 100) && qore_check_cancel(nullptr, "AOT metadata-length scan")) {
                return false;
            }
            uint32_t offset = read_u32_le(sec + 4);
            uint32_t size = read_u32_le(sec + 8);
            uint64_t end = static_cast<uint64_t>(offset) + size;
            if (end > data_area_size) {
                data_area_size = end;
            }
        }
        uint64_t total = static_cast<uint64_t>(data_area_offset) + data_area_size;
        if (total > avail) {
            return false;
        }
        len = static_cast<size_t>(total);
        return true;
    }

    if (compression == QORE_AOT_COMPRESSION_ZLIB) {
        if (avail < QORE_AOT_HEADER_SIZE + 4) {
            return false;
        }
        uint32_t uncompressed_size = read_u32_le(data + QORE_AOT_HEADER_SIZE);
        if (uncompressed_size > 100 * 1024 * 1024) {
            return false;
        }
        if (uncompressed_size == 0) {
            len = QORE_AOT_HEADER_SIZE + 4;
            return true;
        }

        std::vector<uint8_t> out(uncompressed_size);
        z_stream strm{};
        int rc = inflateInit(&strm);
        if (rc != Z_OK) {
            return false;
        }
        strm.next_in = const_cast<Bytef*>(data + QORE_AOT_HEADER_SIZE + 4);
        strm.avail_in = static_cast<uInt>(std::min<size_t>(
            avail - QORE_AOT_HEADER_SIZE - 4, std::numeric_limits<uInt>::max()));
        strm.next_out = out.data();
        strm.avail_out = static_cast<uInt>(std::min<uint32_t>(
            uncompressed_size, std::numeric_limits<uInt>::max()));
        rc = inflate(&strm, Z_FINISH);
        bool ok = rc == Z_STREAM_END && strm.total_out == uncompressed_size;
        size_t consumed = static_cast<size_t>(strm.total_in);
        inflateEnd(&strm);
        if (!ok) {
            return false;
        }
        len = QORE_AOT_HEADER_SIZE + 4 + consumed;
        return len <= avail;
    }

    if (compression == QORE_AOT_COMPRESSION_ZSTD) {
        if (avail < QORE_AOT_HEADER_SIZE + 4) {
            return false;
        }
        uint32_t uncompressed_size = read_u32_le(data + QORE_AOT_HEADER_SIZE);
        if (uncompressed_size > 100 * 1024 * 1024) {
            return false;
        }
        if (!uncompressed_size) {
            len = QORE_AOT_HEADER_SIZE + 4;
            return true;
        }
        const uint8_t* frame = data + QORE_AOT_HEADER_SIZE + 4;
        size_t frame_size = ZSTD_findFrameCompressedSize(frame,
            avail - QORE_AOT_HEADER_SIZE - 4);
        if (ZSTD_isError(frame_size)) {
            return false;
        }
        len = QORE_AOT_HEADER_SIZE + 4 + frame_size;
        return len <= avail;
    }

    return false;
}

static const char* aot_section_type_name(uint16_t type) {
    switch (static_cast<QoreAOTSectionType>(type)) {
        case QoreAOTSectionType::STRINGS: return "STRINGS";
        case QoreAOTSectionType::NAMESPACES: return "NAMESPACES";
        case QoreAOTSectionType::CLASSES: return "CLASSES";
        case QoreAOTSectionType::HASHDECLS: return "HASHDECLS";
        case QoreAOTSectionType::ENUMS: return "ENUMS";
        case QoreAOTSectionType::TYPEDEFS: return "TYPEDEFS";
        case QoreAOTSectionType::CONSTANTS: return "CONSTANTS";
        case QoreAOTSectionType::GLOBALS: return "GLOBALS";
        case QoreAOTSectionType::FUNCTIONS: return "FUNCTIONS";
        case QoreAOTSectionType::METHODS: return "METHODS";
        case QoreAOTSectionType::SLOT_MAPS: return "SLOT_MAPS";
        case QoreAOTSectionType::TOPLEVEL: return "TOPLEVEL";
        case QoreAOTSectionType::FUNC_SOURCES: return "FUNC_SOURCES";
        case QoreAOTSectionType::DEPENDENCIES: return "DEPENDENCIES";
        case QoreAOTSectionType::IMPORT_DEPENDENCIES: return "IMPORT_DEPENDENCIES";
        case QoreAOTSectionType::REEXPORT_MODULES: return "REEXPORT_MODULES";
        case QoreAOTSectionType::PROGRAM_METADATA: return "PROGRAM_METADATA";
        case QoreAOTSectionType::INIT_FUNCS: return "INIT_FUNCS";
        case QoreAOTSectionType::TYPE_TABLE: return "TYPE_TABLE";
        case QoreAOTSectionType::MODULE_PATH_PREPEND: return "MODULE_PATH_PREPEND";
        case QoreAOTSectionType::MODULE_PATH_APPEND: return "MODULE_PATH_APPEND";
        case QoreAOTSectionType::BUILD_INFO: return "BUILD_INFO";
        case QoreAOTSectionType::MODULE_COMMANDS: return "MODULE_COMMANDS";
        case QoreAOTSectionType::PLUGIN_TYPE_REGISTRY: return "PLUGIN_TYPE_REGISTRY";
        case QoreAOTSectionType::PLUGIN_IMPORTS: return "PLUGIN_IMPORTS";
        case QoreAOTSectionType::PLUGIN_HELPER_REFS: return "PLUGIN_HELPER_REFS";
        case QoreAOTSectionType::SYMBOL_INDEX: return "SYMBOL_INDEX";
        case QoreAOTSectionType::CALL_RELOCATIONS: return "CALL_RELOCATIONS";
        case QoreAOTSectionType::DEBUG_IR: return "DEBUG_IR";
        case QoreAOTSectionType::SOURCE_STAT_FINGERPRINT: return "SOURCE_STAT_FINGERPRINT";
        case QoreAOTSectionType::UNRUN_TOP_LEVEL_CODE: return "UNRUN_TOP_LEVEL_CODE";
        case QoreAOTSectionType::FUNCTIONAL_DOMAIN: return "FUNCTIONAL_DOMAIN";
    }
    return "UNKNOWN";
}

static std::string aot_metadata_key(const QoreAOTBinaryReader& reader, size_t size) {
    const QoreAOTBinaryHeader& hdr = reader.getHeader();
    const char* label = reader.getLabel();
    return std::string(label ? label : "") + "|" + std::to_string(hdr.source_hash)
        + "|" + std::to_string(hdr.flags) + "|" + std::to_string(hdr.feature_flags)
        + "|" + std::to_string(size);
}

static bool add_aot_metadata_blob(std::vector<AOTDumpMetadataBlob>& blobs,
        std::set<std::string>& seen, std::vector<uint8_t>&& bytes,
        const std::string& source) {
    if (bytes.size() < QORE_AOT_HEADER_SIZE) {
        return false;
    }
    QoreAOTBinaryReader reader;
    std::string error;
    if (!reader.open(bytes.data(), static_cast<uint32_t>(bytes.size()), error)) {
        return false;
    }
    std::string key = aot_metadata_key(reader, bytes.size());
    if (!seen.insert(key).second) {
        return true;
    }

    AOTDumpMetadataBlob blob;
    blob.source = source;
    blob.bytes = std::move(bytes);
    blobs.push_back(std::move(blob));
    return true;
}

static bool is_aot_metadata_symbol(llvm::StringRef name) {
    return name == "qore_aot_metadata"
        || name == "qore_aot_mod_metadata"
        || name.ends_with("_fragment_blob");
}

static bool is_qore_relevant_symbol(const std::string& name) {
    return name.rfind("qore_", 0) == 0
        || name.rfind("_qore_", 0) == 0
        || name.rfind("_qaot_", 0) == 0
        || name.find("qore_aot") != std::string::npos
        || name.find("qore_module") != std::string::npos;
}

static std::string symbol_section_name(const llvm::object::ObjectFile& obj,
        const llvm::object::SymbolRef& sym) {
    auto sec_or = sym.getSection();
    if (!sec_or) {
        llvm::consumeError(sec_or.takeError());
        return "";
    }
    llvm::object::section_iterator sec = *sec_or;
    if (sec == obj.section_end()) {
        return "";
    }
    auto name_or = sec->getName();
    if (!name_or) {
        llvm::consumeError(name_or.takeError());
        return "";
    }
    return name_or->str();
}

static uint64_t symbol_value(const llvm::object::SymbolRef& sym) {
    auto value_or = sym.getValue();
    if (!value_or) {
        llvm::consumeError(value_or.takeError());
        return 0;
    }
    return *value_or;
}

static uint32_t symbol_flags(const llvm::object::SymbolRef& sym) {
    auto flags_or = sym.getFlags();
    if (!flags_or) {
        llvm::consumeError(flags_or.takeError());
        return 0;
    }
    return *flags_or;
}

static std::string symbol_key(const llvm::object::ObjectFile& obj,
        const llvm::object::SymbolRef& sym) {
    auto name_or = sym.getName();
    std::string name;
    if (name_or) {
        name = name_or->str();
    } else {
        llvm::consumeError(name_or.takeError());
    }
    return name + "|" + std::to_string(symbol_value(sym)) + "|" + symbol_section_name(obj, sym);
}

static char symbol_kind(const llvm::object::SymbolRef& sym) {
    uint32_t flags = symbol_flags(sym);
    if (flags & llvm::object::SymbolRef::SF_Undefined) {
        return 'U';
    }
    if (flags & llvm::object::SymbolRef::SF_Common) {
        return 'C';
    }

    char c = '?';
    auto type_or = sym.getType();
    if (type_or) {
        switch (*type_or) {
            case llvm::object::SymbolRef::ST_Function:
                c = 'T';
                break;
            case llvm::object::SymbolRef::ST_Data:
                c = 'D';
                break;
            case llvm::object::SymbolRef::ST_Debug:
            case llvm::object::SymbolRef::ST_File:
                c = 'N';
                break;
            default:
                break;
        }
    } else {
        llvm::consumeError(type_or.takeError());
    }
    if (c == '?' && (flags & llvm::object::SymbolRef::SF_Executable)) {
        c = 'T';
    }
    if (c == '?' && (flags & llvm::object::SymbolRef::SF_Const)) {
        c = 'R';
    }
    if (!(flags & llvm::object::SymbolRef::SF_Global) && c >= 'A' && c <= 'Z') {
        c = static_cast<char>(std::tolower(c));
    }
    return c;
}

static void extract_aot_metadata_from_object(const llvm::object::ObjectFile& obj,
        std::vector<AOTDumpMetadataBlob>& blobs, std::set<std::string>& seen) {
    auto symbol_sizes = llvm::object::computeSymbolSizes(obj);
    for (const auto& [sym, size] : symbol_sizes) {
        if (!size) {
            continue;
        }
        auto name_or = sym.getName();
        if (!name_or) {
            llvm::consumeError(name_or.takeError());
            continue;
        }
        llvm::StringRef name = *name_or;
        if (!is_aot_metadata_symbol(name)) {
            continue;
        }

        auto sec_or = sym.getSection();
        if (!sec_or) {
            llvm::consumeError(sec_or.takeError());
            continue;
        }
        llvm::object::section_iterator sec = *sec_or;
        if (sec == obj.section_end()) {
            continue;
        }
        auto addr_or = sym.getAddress();
        if (!addr_or) {
            llvm::consumeError(addr_or.takeError());
            continue;
        }
        auto contents_or = sec->getContents();
        if (!contents_or) {
            llvm::consumeError(contents_or.takeError());
            continue;
        }

        uint64_t section_address = sec->getAddress();
        if (*addr_or < section_address) {
            continue;
        }
        uint64_t offset = *addr_or - section_address;
        llvm::StringRef contents = *contents_or;
        uint64_t contents_size = static_cast<uint64_t>(contents.size());
        if (offset > contents_size || size > contents_size - offset) {
            continue;
        }
        const uint8_t* p = reinterpret_cast<const uint8_t*>(contents.data() + offset);
        // A metadata symbol's size is the storage the emitter reserved, which is rounded up to the
        // symbol's alignment; the blob's own header gives its exact length.  Trim to that, because the
        // same metadata is also found by the raw file scan below at its exact length, and
        // add_aot_metadata_blob() keys its duplicate check on the byte count -- so a blob whose length
        // does not land on the alignment boundary is admitted twice and every row of the object's
        // compile contract is emitted twice.  That made an object's contract depend on the parity of its
        // metadata length rather than on its declarations, so two compiles of the same source could
        // publish contracts that differ in their entirety with no symbol differing at all.
        size_t exact_size = 0;
        uint64_t blob_size = find_aot_metadata_length(p, static_cast<size_t>(size), exact_size)
            && exact_size ? static_cast<uint64_t>(exact_size) : size;
        std::vector<uint8_t> bytes(p, p + blob_size);
        add_aot_metadata_blob(blobs, seen, std::move(bytes), "symbol " + name.str());
    }
}

static void scan_aot_metadata_blobs(const std::string& contents,
        std::vector<AOTDumpMetadataBlob>& blobs, std::set<std::string>& seen) {
    size_t pos = 0;
    while ((pos = contents.find("QORD", pos)) != std::string::npos) {
        const uint8_t* data = reinterpret_cast<const uint8_t*>(contents.data() + pos);
        size_t len = 0;
        if (find_aot_metadata_length(data, contents.size() - pos, len) && len > 0) {
            std::vector<uint8_t> bytes(data, data + len);
            add_aot_metadata_blob(blobs, seen, std::move(bytes),
                "embedded metadata at file offset " + std::to_string(pos));
            pos += len;
        } else {
            ++pos;
        }
    }
}

static void print_string_list(const char* label, const std::vector<std::string>& values) {
    if (values.empty()) {
        printf("    %s: (none)\n", label);
        return;
    }
    printf("    %s:\n", label);
    for (const std::string& value : values) {
        printf("      %s\n", value.c_str());
    }
}

static void print_module_commands(const std::vector<AOTModuleCommand>& commands) {
    if (commands.empty()) {
        printf("    module commands: (none)\n");
        return;
    }
    printf("    module commands:\n");
    for (const AOTModuleCommand& command : commands) {
        printf("      %%module-cmd(%s) %s\n", command.module.c_str(), command.command.c_str());
    }
}

static void print_aot_feature_flags(uint64_t flags) {
    static const struct {
        uint64_t bit;
        const char* name;
    } feature_names[] = {
        {QORE_AOT_FEAT_FOREACH_REF, "foreach-ref"},
        {QORE_AOT_FEAT_NATIVE_CAST, "native-cast"},
        {QORE_AOT_FEAT_BLOCK_EXIT, "block-exit"},
        {QORE_AOT_FEAT_DIRECT_INDEX, "direct-index"},
        {QORE_AOT_FEAT_HASH_KEY_ACCESS, "hash-key-access"},
        {QORE_AOT_FEAT_FAST_CALL, "fast-call"},
        {QORE_AOT_FEAT_COMPLEX_RETURN, "complex-return"},
        {QORE_AOT_FEAT_HASH_KEY_STORE, "hash-key-store"},
        {QORE_AOT_FEAT_LIST_INDEX_STORE, "list-index-store"},
        {QORE_AOT_FEAT_TYPE_TABLE, "type-table"},
        {QORE_AOT_FEAT_CONST_PENDING, "const-pending"},
        {QORE_AOT_FEAT_SIG_LINES, "sig-lines"},
        {QORE_AOT_FEAT_CONTEXT_IR, "context-ir"},
        {QORE_AOT_FEAT_LVPATH_SLICE, "lvpath-slice"},
        {QORE_AOT_FEAT_MODULE_PATH_LISTS, "module-path-lists"},
        {QORE_AOT_FEAT_LVPATH_DELETE_EXPR, "lvpath-delete-expr"},
        {QORE_AOT_FEAT_LVPATH_PATTERN, "lvpath-pattern"},
        {QORE_AOT_FEAT_FUNC_CALL_VARIANT, "func-call-variant"},
        {QORE_AOT_FEAT_BACKQUOTE, "backquote"},
        {QORE_AOT_FEAT_FIND, "find"},
        {QORE_AOT_FEAT_BACKGROUND_IR, "background-ir"},
        {QORE_AOT_FEAT_INLINE_CALL_ARGS, "inline-call-args"},
        {QORE_AOT_FEAT_LIST_SELECTOR_RANGE, "list-selector-range"},
        {QORE_AOT_FEAT_ENTRY_STMT_LINES, "entry-stmt-lines"},
        {QORE_AOT_FEAT_PARSE_REF_TYPE, "parse-ref-type"},
        {QORE_AOT_FEAT_STMT_LOC_TABLE, "stmt-loc-table"},
        {QORE_AOT_FEAT_DEBUG_IR, "debug-ir"},
        {QORE_AOT_FEAT_SELF_CALL_ARGS, "self-call-args"},
        {QORE_AOT_FEAT_BODY_LOCAL_SLOT, "body-local-slot"},
        {QORE_AOT_FEAT_BCA_LINES, "bca-lines"},
        {QORE_AOT_FEAT_BCA_NATIVE_ARGS, "bca-native-args"},
        {QORE_AOT_FEAT_CLOSURE_VARARGS_FLAGS, "closure-varargs-flags"},
        {QORE_AOT_FEAT_CONTAINER_TYPEINFO, "container-typeinfo"},
        {QORE_AOT_FEAT_CLASS_HASH, "class-hash"},
        {QORE_AOT_FEAT_METHOD_SYNC, "method-sync"},
        {QORE_AOT_FEAT_TYPED_VALUE_CONTAINERS, "typed-value-containers"},
        {QORE_AOT_FEAT_MODULE_COMMANDS, "module-commands"},
        {QORE_AOT_FEAT_WIDE_IR_OPERANDS, "wide-ir-operands"},
        {QORE_AOT_FEAT_WIDE_LOC_TABLES, "wide-loc-tables"},
        {QORE_AOT_FEAT_LOCAL_DECL_ORDINAL, "local-decl-ordinal"},
        {QORE_AOT_FEAT_CLASS_INJECTION, "class-injection"},
        {QORE_AOT_FEAT_VARIANT_PARSE_OPTIONS, "variant-parse-options"},
        {QORE_AOT_FEAT_BCA_NAMED_ARG_MAP, "bca-named-arg-map"},
        {QORE_AOT_FEAT_NEW_OBJECT_TYPEINFO, "new-object-typeinfo"},
        {QORE_AOT_FEAT_CLASS_TYPE_PARAMS, "class-type-params"},
        {QORE_AOT_FEAT_CLASS_PARAM_BASES, "class-param-bases"},
        {QORE_AOT_FEAT_CLASS_RAW_GENERIC, "class-raw-generic"},
        {QORE_AOT_FEAT_STATIC_CALL_RECEIVER_TYPE, "static-call-receiver-type"},
        {QORE_AOT_FEAT_HASHDECL_TYPE_PARAMS, "hashdecl-type-params"},
        {QORE_AOT_FEAT_TYPE_PARAM_DEFAULTS, "type-param-defaults"},
        {QORE_AOT_FEAT_HASHDECL_PARAM_PARENTS, "hashdecl-param-parents"},
        {QORE_AOT_FEAT_TYPE_PARAM_BOUNDS, "type-param-bounds"},
        {QORE_AOT_FEAT_PLUGIN_DISPATCH, "plugin-dispatch"},
        {QORE_AOT_FEAT_COMPLEX_BUFFER_INIT_KIND, "complex-buffer-init-kind"},
        {QORE_AOT_FEAT_READONLY_LOCALS, "readonly-locals"},
        {QORE_AOT_FEAT_CONST_METHODS, "const-methods"},
        {QORE_AOT_FEAT_CALL_CLOSURE_REF_ARGS, "call-closure-ref-args"},
        {QORE_AOT_FEAT_TYPED_PHI, "typed-phi"},
        {QORE_AOT_FEAT_CALL_RELOCATIONS, "call-relocations"},
        {QORE_AOT_FEAT_HASH_DEREF_TYPEINFO, "hash-deref-typeinfo"},
    };

    printf("    features: 0x%016llx", static_cast<unsigned long long>(flags));
    bool first = true;
    for (const auto& feature : feature_names) {
        if (flags & feature.bit) {
            printf("%s%s", first ? " (" : ", ", feature.name);
            first = false;
        }
    }
    if (!first) {
        printf(")");
    }
    printf("\n");

    uint64_t unsupported = flags & ~QORE_AOT_SUPPORTED_FEATURES;
    if (unsupported) {
        printf("    unsupported features in this runtime: 0x%016llx\n",
            static_cast<unsigned long long>(unsupported));
    }
}

struct AOTSlotMapDumpSummary {
    struct ExprTreeDetail {
        std::string function;
        uint8_t root_kind = 0;
        uint8_t top_kind = 0;
        uint8_t container_kind = 0;
        uint16_t slot = 0xffff;
        bool top_level = false;
    };

    uint32_t functions = 0;
    uint64_t local_slots = 0;
    uint64_t global_slots = 0;
    uint64_t expr_slots = 0;
    uint64_t stmt_slots = 0;
    uint64_t regex_slots = 0;
    uint64_t body_locals = 0;
    uint64_t lv_path_slots = 0;
    uint32_t unsupported_functions = 0;
    uint32_t malformed_entries = 0;
    std::map<uint8_t, uint64_t> top_expr_kinds;
    std::map<uint8_t, uint64_t> all_expr_kinds;
    std::map<uint8_t, uint64_t> expr_tree_root_kinds;
    std::vector<ExprTreeDetail> expr_tree_details;
    std::vector<std::string> expr_tree_functions;
    std::vector<std::string> generic_eval_functions;
};

struct AOTDumpExprContext {
    uint8_t top_kind = 0;
    uint8_t container_kind = 0;
    uint16_t slot = 0xffff;
};

static bool dump_need(const uint8_t* p, const uint8_t* end, size_t n) {
    return p && end && p <= end && static_cast<size_t>(end - p) >= n;
}

static bool dump_skip_bytes(const uint8_t*& p, const uint8_t* end, size_t n) {
    if (!dump_need(p, end, n)) {
        return false;
    }
    p += n;
    return true;
}

static bool dump_read_u8(const uint8_t*& p, const uint8_t* end, uint8_t& v) {
    if (!dump_need(p, end, 1)) {
        return false;
    }
    v = QoreAOTBinaryReader::readU8(p);
    return true;
}

static bool dump_read_u16(const uint8_t*& p, const uint8_t* end, uint16_t& v) {
    if (!dump_need(p, end, 2)) {
        return false;
    }
    v = QoreAOTBinaryReader::readU16(p);
    return true;
}

static bool dump_read_u32(const uint8_t*& p, const uint8_t* end, uint32_t& v) {
    if (!dump_need(p, end, 4)) {
        return false;
    }
    v = QoreAOTBinaryReader::readU32(p);
    return true;
}

static bool dump_skip_string_ref(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, const char** value = nullptr) {
    if (!dump_need(p, end, 4)) {
        return false;
    }
    const char* s = reader.readStringRef(p);
    if (value) {
        *value = s;
    }
    return true;
}

static bool dump_skip_len_string_ref(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end) {
    uint32_t len = 0;
    return dump_read_u32(p, end, len) && dump_skip_string_ref(reader, p, end);
}

static const char* dump_aot_expr_kind_name(uint8_t kind) {
    const auto* info = getAOTExprSlotKindInfo(kind);
    if (info && info->name) {
        return info->name;
    }
    switch (static_cast<AOTExprKind>(kind)) {
        case AOTExprKind::HASH_LITERAL: return "HASH_LITERAL";
        case AOTExprKind::HASH_DEREF: return "HASH_DEREF";
        case AOTExprKind::PARSE_REF: return "PARSE_REF";
        case AOTExprKind::LIST_LITERAL: return "LIST_LITERAL";
        case AOTExprKind::PLUS: return "PLUS";
        case AOTExprKind::SQUARE_BRACKET: return "SQUARE_BRACKET";
        case AOTExprKind::PARSE_HASH: return "PARSE_HASH";
        case AOTExprKind::EXISTS: return "EXISTS";
        case AOTExprKind::IMPLICIT_ARG: return "IMPLICIT_ARG";
        case AOTExprKind::MINUS: return "MINUS";
        case AOTExprKind::KEYS: return "KEYS";
        case AOTExprKind::MULTIPLY: return "MULTIPLY";
        case AOTExprKind::DIVIDE: return "DIVIDE";
        case AOTExprKind::MODULO: return "MODULO";
        case AOTExprKind::IMPLICIT_ELEM: return "IMPLICIT_ELEM";
        case AOTExprKind::INSTANCEOF: return "INSTANCEOF";
        case AOTExprKind::REGEX_MATCH: return "REGEX_MATCH";
        case AOTExprKind::REGEX_NMATCH: return "REGEX_NMATCH";
        case AOTExprKind::REGEX_EXTRACT: return "REGEX_EXTRACT";
        case AOTExprKind::PRE_INC: return "PRE_INC";
        case AOTExprKind::PRE_DEC: return "PRE_DEC";
        case AOTExprKind::POST_INC: return "POST_INC";
        case AOTExprKind::POST_DEC: return "POST_DEC";
        case AOTExprKind::LOG_EQ: return "LOG_EQ";
        case AOTExprKind::LOG_NE: return "LOG_NE";
        case AOTExprKind::LOG_LT: return "LOG_LT";
        case AOTExprKind::LOG_GT: return "LOG_GT";
        case AOTExprKind::LOG_LE: return "LOG_LE";
        case AOTExprKind::LOG_GE: return "LOG_GE";
        case AOTExprKind::LOG_AND: return "LOG_AND";
        case AOTExprKind::LOG_OR: return "LOG_OR";
        case AOTExprKind::CALLREF_CALL: return "CALLREF_CALL";
        case AOTExprKind::LOG_NOT: return "LOG_NOT";
        case AOTExprKind::TRIM: return "TRIM";
        case AOTExprKind::CHOMP: return "CHOMP";
        case AOTExprKind::POP: return "POP";
        case AOTExprKind::SHIFT: return "SHIFT";
        case AOTExprKind::PUSH: return "PUSH";
        case AOTExprKind::UNSHIFT: return "UNSHIFT";
        case AOTExprKind::ELEMENTS: return "ELEMENTS";
        case AOTExprKind::DELETE: return "DELETE";
        case AOTExprKind::REMOVE: return "REMOVE";
        case AOTExprKind::BACKGROUND: return "BACKGROUND";
        case AOTExprKind::CONTEXT_REF: return "CONTEXT_REF";
        case AOTExprKind::CONTEXT_ROW: return "CONTEXT_ROW";
        case AOTExprKind::COMPLEX_CONTEXT_REF: return "COMPLEX_CONTEXT_REF";
        case AOTExprKind::NULL_COAL: return "NULL_COAL";
        case AOTExprKind::VALUE_COAL: return "VALUE_COAL";
        case AOTExprKind::QUESTION: return "QUESTION";
        case AOTExprKind::FOLDL: return "FOLDL";
        case AOTExprKind::FOLDR: return "FOLDR";
        case AOTExprKind::MAP: return "MAP";
        case AOTExprKind::MAP_SELECT: return "MAP_SELECT";
        case AOTExprKind::HASH_MAP_OP: return "HASH_MAP";
        case AOTExprKind::HASH_MAP_SELECT_OP: return "HASH_MAP_SELECT";
        case AOTExprKind::SELECT: return "SELECT";
        default: break;
    }
    return "UNKNOWN";
}

static const char* dump_aot_expr_node_kind_name(uint8_t kind) {
    const auto* info = getAOTExprNodeKindInfo(kind);
    return info && info->name ? info->name : "UNKNOWN";
}

static void dump_record_expr_tree_root(AOTSlotMapDumpSummary& summary, uint8_t root_kind,
        const std::string& func_name, bool top_level, const AOTDumpExprContext& ctx) {
    ++summary.expr_tree_root_kinds[root_kind];
    summary.expr_tree_details.push_back({
        func_name,
        root_kind,
        ctx.top_kind,
        ctx.container_kind,
        ctx.slot,
        top_level,
    });
}

static void dump_record_expr_kind(AOTSlotMapDumpSummary& summary, uint8_t kind,
        bool top_level, const std::string& func_name) {
    ++summary.all_expr_kinds[kind];
    if (top_level) {
        ++summary.top_expr_kinds[kind];
    }
    if (kind == static_cast<uint8_t>(AOTExprKind::EXPR_TREE)) {
        if (std::find(summary.expr_tree_functions.begin(), summary.expr_tree_functions.end(),
                func_name) == summary.expr_tree_functions.end()) {
            summary.expr_tree_functions.push_back(func_name);
        }
    } else if (kind == static_cast<uint8_t>(AOTExprKind::GENERIC_EVAL)) {
        if (std::find(summary.generic_eval_functions.begin(), summary.generic_eval_functions.end(),
                func_name) == summary.generic_eval_functions.end()) {
            summary.generic_eval_functions.push_back(func_name);
        }
    }
}

static bool dump_skip_inline_expr(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, AOTSlotMapDumpSummary& summary,
        const std::string& func_name, const AOTDumpExprContext& ctx);

static bool dump_skip_inline_expr_list(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, uint8_t count,
        AOTSlotMapDumpSummary& summary, const std::string& func_name,
        const AOTDumpExprContext& ctx) {
    for (uint8_t i = 0; i < count; ++i) {
        if (!dump_skip_inline_expr(reader, p, end, summary, func_name, ctx)) {
            return false;
        }
    }
    return true;
}

static bool dump_skip_serialized_value_no_summary(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end);

static bool dump_skip_expr_payload(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, uint8_t kind, bool slot_form,
        AOTSlotMapDumpSummary& summary, const std::string& func_name,
        const AOTDumpExprContext& ctx) {
    AOTDumpExprContext child_ctx = ctx;
    child_ctx.container_kind = kind;
    auto skip_n_args = [&](uint8_t count) {
        return dump_skip_inline_expr_list(reader, p, end, count, summary, func_name,
            child_ctx);
    };

    switch (static_cast<AOTExprKind>(kind)) {
        case AOTExprKind::FUNC_CALL:
            if (!dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            if (!slot_form || (reader.getHeader().feature_flags & QORE_AOT_FEAT_FUNC_CALL_VARIANT) != 0) {
                if (!dump_skip_string_ref(reader, p, end)) {
                    return false;
                }
            }
            if (!slot_form && (reader.getHeader().feature_flags & QORE_AOT_FEAT_INLINE_CALL_ARGS) != 0) {
                uint8_t nargs = 0;
                return dump_read_u8(p, end, nargs) && skip_n_args(nargs);
            }
            return true;

        case AOTExprKind::SELF_METHOD_CALL:
            if (!dump_skip_string_ref(reader, p, end) || !dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            if (!slot_form && (reader.getHeader().feature_flags & QORE_AOT_FEAT_SELF_CALL_ARGS) != 0) {
                uint8_t nargs = 0;
                return dump_read_u8(p, end, nargs) && skip_n_args(nargs);
            }
            return true;

        case AOTExprKind::STATIC_VARREF:
        case AOTExprKind::CONST_ENUM:
        case AOTExprKind::BOUND_METHOD_REF:
        case AOTExprKind::STATIC_METHOD_REF:
            return dump_skip_string_ref(reader, p, end)
                && dump_skip_string_ref(reader, p, end);

        case AOTExprKind::STATIC_METHOD_CALL: {
            uint8_t nargs = 0;
            if (!dump_skip_string_ref(reader, p, end)
                    || !dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            if ((reader.getHeader().feature_flags & QORE_AOT_FEAT_STATIC_CALL_RECEIVER_TYPE) != 0
                    && !dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            return dump_read_u8(p, end, nargs) && skip_n_args(nargs);
        }

        case AOTExprKind::NEW_OBJECT:
        case AOTExprKind::SCOPED_NEW_OBJECT:
            if (slot_form) {
                if (!dump_skip_string_ref(reader, p, end)
                        || !dump_skip_string_ref(reader, p, end)) {
                    return false;
                }
                return (reader.getHeader().feature_flags & QORE_AOT_FEAT_NEW_OBJECT_TYPEINFO) == 0
                    || dump_skip_string_ref(reader, p, end);
            } else {
                uint8_t nargs = 0;
                return dump_skip_string_ref(reader, p, end)
                    && dump_read_u8(p, end, nargs)
                    && skip_n_args(nargs);
            }

        case AOTExprKind::CALLREF_CALL: {
            uint8_t nargs = 0;
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_read_u8(p, end, nargs)
                && skip_n_args(nargs);
        }

        case AOTExprKind::RUNTIME_CONST_REF:
        case AOTExprKind::SELF_VARREF:
        case AOTExprKind::LOCAL_VARREF:
        case AOTExprKind::GLOBAL_VARREF:
        case AOTExprKind::CONST_NUMBER:
        case AOTExprKind::CONST_BINARY:
        case AOTExprKind::CONST_STRING:
        case AOTExprKind::FUNC_CALL_REF:
        case AOTExprKind::SELF_METHOD_REF:
            return dump_skip_string_ref(reader, p, end);

        case AOTExprKind::PLUS:
        case AOTExprKind::SQUARE_BRACKET:
        case AOTExprKind::MINUS:
        case AOTExprKind::MULTIPLY:
        case AOTExprKind::DIVIDE:
        case AOTExprKind::MODULO:
        case AOTExprKind::BIT_AND:
        case AOTExprKind::BIT_OR:
        case AOTExprKind::BIT_XOR:
        case AOTExprKind::SHIFT_LEFT:
        case AOTExprKind::SHIFT_RIGHT:
        case AOTExprKind::NULL_COAL:
        case AOTExprKind::VALUE_COAL:
        case AOTExprKind::FOLDL:
        case AOTExprKind::FOLDR:
        case AOTExprKind::MAP:
        case AOTExprKind::SELECT:
        case AOTExprKind::LOG_AND:
        case AOTExprKind::LOG_OR:
        case AOTExprKind::RANGE:
        case AOTExprKind::ASSIGN:
        case AOTExprKind::PLUS_EQ:
        case AOTExprKind::MINUS_EQ:
        case AOTExprKind::MULTIPLY_EQ:
        case AOTExprKind::DIVIDE_EQ:
        case AOTExprKind::MODULO_EQ:
        case AOTExprKind::AND_EQ:
        case AOTExprKind::OR_EQ:
        case AOTExprKind::XOR_EQ:
        case AOTExprKind::SHL_EQ:
        case AOTExprKind::SHR_EQ:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::MAP_SELECT:
        case AOTExprKind::HASH_MAP_OP:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::HASH_MAP_SELECT_OP:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::EXISTS:
        case AOTExprKind::KEYS:
        case AOTExprKind::ITERATE:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::STREAMING:
            // the streaming operator kind, the predicate and the source
            return dump_skip_bytes(p, end, 1)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::DEFERRED_STATIC_METHOD_REF:
            // the class path and the method name
            return dump_skip_string_ref(reader, p, end)
                && dump_skip_string_ref(reader, p, end);

        case AOTExprKind::DEFERRED_FUNCTION_REF:
            // the function path
            return dump_skip_string_ref(reader, p, end);

        case AOTExprKind::UNSUPPORTED:
            // a compile-time marker that is never written: a payload with it is malformed
            return false;

        case AOTExprKind::IMPLICIT_ARG:
            return dump_skip_bytes(p, end, 8);

        case AOTExprKind::IMPLICIT_ELEM:
            return true;

        case AOTExprKind::INSTANCEOF:
            return dump_skip_string_ref(reader, p, end)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::REGEX_MATCH:
        case AOTExprKind::REGEX_NMATCH:
        case AOTExprKind::REGEX_EXTRACT:
            return dump_skip_string_ref(reader, p, end)
                && dump_skip_bytes(p, end, 8)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::CONTEXT_REF:
            return dump_skip_string_ref(reader, p, end);

        case AOTExprKind::CONTEXT_ROW:
            return true;

        case AOTExprKind::COMPLEX_CONTEXT_REF:
            return dump_skip_string_ref(reader, p, end)
                && dump_skip_string_ref(reader, p, end)
                && dump_skip_bytes(p, end, 8);

        case AOTExprKind::PRE_INC:
        case AOTExprKind::PRE_DEC:
        case AOTExprKind::POST_INC:
        case AOTExprKind::POST_DEC:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::LOG_EQ:
        case AOTExprKind::LOG_NE:
        case AOTExprKind::LOG_AEQ:
        case AOTExprKind::LOG_ANE:
        case AOTExprKind::LOG_LT:
        case AOTExprKind::LOG_GT:
        case AOTExprKind::LOG_LE:
        case AOTExprKind::LOG_GE:
        case AOTExprKind::PUSH:
        case AOTExprKind::UNSHIFT:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::LOG_NOT:
        case AOTExprKind::TRIM:
        case AOTExprKind::CHOMP:
        case AOTExprKind::POP:
        case AOTExprKind::SHIFT:
        case AOTExprKind::ELEMENTS:
        case AOTExprKind::DELETE:
        case AOTExprKind::REMOVE:
        case AOTExprKind::BACKGROUND:
        case AOTExprKind::UNARY_MINUS:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::QUESTION:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::SQUARE_BRACKET_RANGE:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::CALL_REF:
        case AOTExprKind::OBJ_METHOD_REF:
        case AOTExprKind::CONST_NOTHING:
        case AOTExprKind::CONST_NULL:
        case AOTExprKind::GENERIC_EVAL:
            return true;

        case AOTExprKind::CONST_INT:
        case AOTExprKind::CONST_FLOAT:
            return slot_form ? dump_skip_string_ref(reader, p, end)
                : dump_skip_bytes(p, end, 8);

        case AOTExprKind::CONST_BOOL:
            return slot_form ? dump_skip_string_ref(reader, p, end)
                : dump_skip_bytes(p, end, 1);

        case AOTExprKind::CONST_VALUE: {
            return dump_skip_serialized_value_no_summary(reader, p, end);
        }

        case AOTExprKind::HASHDECL_NEW:
        case AOTExprKind::COMPLEX_HASH_NEW: {
            uint8_t nargs = 0;
            return dump_skip_string_ref(reader, p, end)
                && dump_read_u8(p, end, nargs)
                && skip_n_args(nargs);
        }

        case AOTExprKind::COMPLEX_LIST_NEW: {
            uint8_t has_arg = 0;
            if (!dump_skip_string_ref(reader, p, end)
                    || !dump_read_u8(p, end, has_arg)) {
                return false;
            }
            return !has_arg
                || dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);
        }

        case AOTExprKind::COMPLEX_BUFFER_NEW: {
            uint8_t has_arg = 0;
            if (!dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            if ((reader.getHeader().feature_flags & QORE_AOT_FEAT_COMPLEX_BUFFER_INIT_KIND) != 0
                    && !dump_skip_bytes(p, end, 1)) {
                return false;
            }
            if (!dump_read_u8(p, end, has_arg)) {
                return false;
            }
            return !has_arg
                || dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);
        }

        case AOTExprKind::HASH_LITERAL: {
            uint8_t count = 0;
            if (!dump_read_u8(p, end, count)) {
                return false;
            }
            for (uint8_t i = 0; i < count; ++i) {
                if (!dump_skip_string_ref(reader, p, end)
                        || !dump_skip_inline_expr(reader, p, end, summary, func_name,
                            child_ctx)) {
                    return false;
                }
            }
            return true;
        }

        case AOTExprKind::PARSE_HASH: {
            uint8_t count = 0;
            if (!dump_read_u8(p, end, count)) {
                return false;
            }
            for (uint8_t i = 0; i < count; ++i) {
                if (!dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                        || !dump_skip_inline_expr(reader, p, end, summary, func_name,
                            child_ctx)) {
                    return false;
                }
            }
            return true;
        }

        case AOTExprKind::LIST_LITERAL: {
            uint8_t count = 0;
            return dump_read_u8(p, end, count) && skip_n_args(count);
        }

        case AOTExprKind::HASH_DEREF:
            if ((reader.getHeader().feature_flags & QORE_AOT_FEAT_HASH_DEREF_TYPEINFO) != 0
                    && !dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::PARSE_REF:
            if ((reader.getHeader().feature_flags & QORE_AOT_FEAT_PARSE_REF_TYPE) != 0
                    && !dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::CAST_HASHDECL:
        case AOTExprKind::CAST_COMPLEX_HASH:
        case AOTExprKind::CAST_COMPLEX_LIST:
        case AOTExprKind::CAST_CLASS:
        case AOTExprKind::CAST_ENUM:
        case AOTExprKind::CAST_SCALAR: {
            if (!dump_skip_string_ref(reader, p, end) || !dump_skip_bytes(p, end, 1)) {
                return false;
            }
            if (slot_form) {
                return true;
            }
            uint8_t has_inner = 0;
            if (!dump_read_u8(p, end, has_inner)) {
                return false;
            }
            return !has_inner
                || dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);
        }

        case AOTExprKind::DOT_EVAL_TARGET: {
            if (!dump_skip_string_ref(reader, p, end)
                    || !dump_skip_string_ref(reader, p, end)
                    || !dump_skip_bytes(p, end, 1)) {
                return false;
            }
            if (!slot_form) {
                uint8_t nargs = 0;
                return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx)
                    && dump_read_u8(p, end, nargs)
                    && skip_n_args(nargs);
            }
            return true;
        }

        case AOTExprKind::OBJ_METHOD_REF_EXPR:
            return dump_skip_string_ref(reader, p, end)
                && dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::DOT_EVAL_EXPR:
            return dump_skip_inline_expr(reader, p, end, summary, func_name, child_ctx);

        case AOTExprKind::CLOSURE_CREATE: {
            if (!dump_skip_string_ref(reader, p, end)
                    || !dump_skip_string_ref(reader, p, end)
                    || !dump_skip_string_ref(reader, p, end)) {
                return false;
            }
            uint16_t nparams = 0;
            if (!dump_read_u16(p, end, nparams)) {
                return false;
            }
            for (uint16_t i = 0; i < nparams; ++i) {
                if (!dump_skip_string_ref(reader, p, end)
                        || !dump_skip_string_ref(reader, p, end)) {
                    return false;
                }
                uint8_t has_default = 0;
                if (!dump_read_u8(p, end, has_default)) {
                    return false;
                }
                if (has_default && !dump_skip_serialized_value_no_summary(reader, p, end)) {
                    return false;
                }
            }
            if ((reader.getHeader().feature_flags & QORE_AOT_FEAT_CLOSURE_VARARGS_FLAGS) != 0) {
                if (!dump_skip_bytes(p, end, 2)) {
                    return false;
                }
            } else {
                if (!dump_skip_bytes(p, end, 1)) {
                    return false;
                }
            }
            uint16_t ncaptured = 0;
            if (!dump_read_u16(p, end, ncaptured)) {
                return false;
            }
            for (uint16_t i = 0; i < ncaptured; ++i) {
                if (!dump_skip_string_ref(reader, p, end) || !dump_skip_bytes(p, end, 4)) {
                    return false;
                }
            }
            uint8_t has_ir = 0;
            if (!dump_read_u8(p, end, has_ir)) {
                return false;
            }
            if (has_ir) {
                uint32_t ir_size = 0;
                if (!dump_read_u32(p, end, ir_size) || !dump_skip_bytes(p, end, ir_size)) {
                    return false;
                }
            }
            return true;
        }

        case AOTExprKind::EXPR_TREE: {
            uint32_t blob_size = 0;
            if (!dump_read_u32(p, end, blob_size)) {
                return false;
            }
            if (blob_size > 0 && dump_need(p, end, blob_size)) {
                dump_record_expr_tree_root(summary, *p, func_name, slot_form, ctx);
            }
            return dump_skip_bytes(p, end, blob_size);
        }
    }

    return false;
}

static bool dump_skip_inline_expr(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, AOTSlotMapDumpSummary& summary,
        const std::string& func_name, const AOTDumpExprContext& ctx) {
    uint8_t kind = 0;
    if (!dump_read_u8(p, end, kind)) {
        return false;
    }
    dump_record_expr_kind(summary, kind, false, func_name);
    return dump_skip_expr_payload(reader, p, end, kind, false, summary, func_name, ctx);
}

static bool summarize_aot_slot_maps(const QoreAOTBinaryReader& reader,
        AOTSlotMapDumpSummary& summary, std::string& error) {
    const QoreAOTSectionHeader* sec = reader.findSection(QoreAOTSectionType::SLOT_MAPS);
    if (!sec) {
        return true;
    }
    const uint8_t* p = reader.getSectionData(*sec);
    if (!p) {
        error = "invalid SLOT_MAPS section";
        return false;
    }
    const uint8_t* end = p + sec->size;
    uint32_t num_funcs = 0;
    if (!dump_read_u32(p, end, num_funcs)) {
        error = "truncated SLOT_MAPS header";
        return false;
    }
    summary.functions = num_funcs;

    for (uint32_t f = 0; f < num_funcs; ++f) {
        const uint8_t* entry_start = p;
        uint32_t entry_size = 0;
        if (!dump_read_u32(p, end, entry_size)) {
            error = "truncated SLOT_MAPS entry header";
            return false;
        }
        if (static_cast<size_t>(end - p) < entry_size) {
            error = "SLOT_MAPS entry overruns section";
            return false;
        }
        const uint8_t* entry_end = p + entry_size;
        const char* fname = nullptr;
        if (!dump_skip_string_ref(reader, p, entry_end, &fname)) {
            ++summary.malformed_entries;
            p = entry_start + 4 + entry_size;
            continue;
        }
        std::string func_name = fname && *fname ? fname : "(unnamed)";

        uint16_t num_locals = 0, num_globals = 0, num_exprs = 0, num_stmts = 0;
        uint16_t num_regex = 0, num_body_locals = 0;
        uint8_t has_unsupported = 0, num_lv_paths = 0;
        if (!dump_read_u16(p, entry_end, num_locals)
                || !dump_read_u16(p, entry_end, num_globals)
                || !dump_read_u16(p, entry_end, num_exprs)
                || !dump_read_u16(p, entry_end, num_stmts)
                || !dump_read_u16(p, entry_end, num_regex)
                || !dump_read_u16(p, entry_end, num_body_locals)
                || !dump_read_u8(p, entry_end, has_unsupported)
                || !dump_read_u8(p, entry_end, num_lv_paths)) {
            ++summary.malformed_entries;
            p = entry_start + 4 + entry_size;
            continue;
        }

        summary.local_slots += num_locals;
        summary.global_slots += num_globals;
        summary.expr_slots += num_exprs;
        summary.stmt_slots += num_stmts;
        summary.regex_slots += num_regex;
        summary.body_locals += num_body_locals;
        summary.lv_path_slots += num_lv_paths;
        if (has_unsupported) {
            ++summary.unsupported_functions;
        }

        const size_t local_slot_extra_bytes =
            (reader.getHeader().feature_flags & QORE_AOT_FEAT_LOCAL_DECL_ORDINAL) != 0 ? 7 : 3;
        const size_t global_slot_extra_bytes =
            (reader.getHeader().feature_flags & QORE_AOT_FEAT_GLOBAL_SLOT_FLAGS) != 0 ? 2 : 1;
        bool malformed = false;
        for (uint16_t i = 0; i < num_locals && !malformed; ++i) {
            malformed = !dump_skip_string_ref(reader, p, entry_end)
                || !dump_skip_string_ref(reader, p, entry_end)
                || !dump_skip_bytes(p, entry_end, local_slot_extra_bytes);
        }
        for (uint16_t i = 0; i < num_globals && !malformed; ++i) {
            malformed = !dump_skip_string_ref(reader, p, entry_end)
                || !dump_skip_string_ref(reader, p, entry_end)
                || !dump_skip_bytes(p, entry_end, global_slot_extra_bytes);
        }
        for (uint16_t i = 0; i < num_exprs && !malformed; ++i) {
            uint8_t kind = 0;
            if (!dump_read_u8(p, entry_end, kind)) {
                malformed = true;
                break;
            }
            dump_record_expr_kind(summary, kind, true, func_name);
            AOTDumpExprContext ctx;
            ctx.top_kind = kind;
            ctx.container_kind = kind;
            ctx.slot = i;
            if (!dump_skip_expr_payload(reader, p, entry_end, kind, true, summary, func_name, ctx)) {
                malformed = true;
                break;
            }
        }
        if (malformed) {
            ++summary.malformed_entries;
        }
        p = entry_start + 4 + entry_size;
    }

    return true;
}

static void print_aot_slot_map_summary(const QoreAOTBinaryReader& reader) {
    AOTSlotMapDumpSummary summary;
    std::string error;
    if (!summarize_aot_slot_maps(reader, summary, error)) {
        printf("    slot maps: error: %s\n", error.c_str());
        return;
    }
    if (!summary.functions) {
        printf("    slot maps: (none)\n");
        return;
    }

    uint64_t top_expr_tree = summary.top_expr_kinds[static_cast<uint8_t>(AOTExprKind::EXPR_TREE)];
    uint64_t all_expr_tree = summary.all_expr_kinds[static_cast<uint8_t>(AOTExprKind::EXPR_TREE)];
    uint64_t top_generic = summary.top_expr_kinds[static_cast<uint8_t>(AOTExprKind::GENERIC_EVAL)];
    uint64_t all_generic = summary.all_expr_kinds[static_cast<uint8_t>(AOTExprKind::GENERIC_EVAL)];

    printf("    slot maps: functions=%u locals=%llu globals=%llu expr-slots=%llu stmts=%llu "
           "regex=%llu body-locals=%llu lvpaths=%llu unsupported-functions=%u malformed=%u\n",
        summary.functions,
        static_cast<unsigned long long>(summary.local_slots),
        static_cast<unsigned long long>(summary.global_slots),
        static_cast<unsigned long long>(summary.expr_slots),
        static_cast<unsigned long long>(summary.stmt_slots),
        static_cast<unsigned long long>(summary.regex_slots),
        static_cast<unsigned long long>(summary.body_locals),
        static_cast<unsigned long long>(summary.lv_path_slots),
        summary.unsupported_functions,
        summary.malformed_entries);
    printf("      fallback exprs: EXPR_TREE=%llu top/%llu total, GENERIC_EVAL=%llu top/%llu total\n",
        static_cast<unsigned long long>(top_expr_tree),
        static_cast<unsigned long long>(all_expr_tree),
        static_cast<unsigned long long>(top_generic),
        static_cast<unsigned long long>(all_generic));

    auto print_limited_names = [](const char* label, const std::vector<std::string>& values) {
        if (values.empty()) {
            return;
        }
        printf("      %s:", label);
        size_t limit = std::min<size_t>(values.size(), 8);
        for (size_t i = 0; i < limit; ++i) {
            printf("%s%s", i ? ", " : " ", values[i].c_str());
        }
        if (values.size() > limit) {
            printf(", ... +%zu", values.size() - limit);
        }
        printf("\n");
    };
    print_limited_names("EXPR_TREE functions", summary.expr_tree_functions);
    print_limited_names("GENERIC_EVAL functions", summary.generic_eval_functions);

    if (!summary.expr_tree_root_kinds.empty()) {
        printf("      EXPR_TREE root nodes:\n");
        for (const auto& [kind, count] : summary.expr_tree_root_kinds) {
            printf("        %-20s (%3u): %llu\n", dump_aot_expr_node_kind_name(kind), kind,
                static_cast<unsigned long long>(count));
        }
    }

    if (dump_sections && !summary.top_expr_kinds.empty()) {
        if (!summary.expr_tree_details.empty()) {
            printf("      EXPR_TREE details:\n");
            for (const auto& detail : summary.expr_tree_details) {
                printf("        %s %-20s (%3u) top=%s slot=%u container=%s: %s\n",
                    detail.top_level ? "top   " : "nested",
                    dump_aot_expr_node_kind_name(detail.root_kind),
                    detail.root_kind,
                    dump_aot_expr_kind_name(detail.top_kind),
                    detail.slot == 0xffff ? 0 : detail.slot,
                    dump_aot_expr_kind_name(detail.container_kind),
                detail.function.c_str());
            }
        }
        printf("      top expr slot kinds:\n");
        for (const auto& [kind, count] : summary.top_expr_kinds) {
            printf("        %-20s (%3u): %llu\n", dump_aot_expr_kind_name(kind), kind,
                static_cast<unsigned long long>(count));
        }
    }
    if (dump_sections && summary.all_expr_kinds.size() != summary.top_expr_kinds.size()) {
        printf("      all encoded expr kinds:\n");
        for (const auto& [kind, count] : summary.all_expr_kinds) {
            printf("        %-20s (%3u): %llu\n", dump_aot_expr_kind_name(kind), kind,
                static_cast<unsigned long long>(count));
        }
    }
}

static const char* dump_aot_value_tag_name(uint8_t tag) {
    switch (static_cast<QoreAOTValueTag>(tag)) {
        case QoreAOTValueTag::VT_NOTHING: return "NOTHING";
        case QoreAOTValueTag::VT_NULL: return "NULL";
        case QoreAOTValueTag::VT_BOOL: return "BOOL";
        case QoreAOTValueTag::VT_INT64: return "INT64";
        case QoreAOTValueTag::VT_FLOAT64: return "FLOAT64";
        case QoreAOTValueTag::VT_STRING: return "STRING";
        case QoreAOTValueTag::VT_ABS_DATE: return "ABS_DATE";
        case QoreAOTValueTag::VT_REL_DATE: return "REL_DATE";
        case QoreAOTValueTag::VT_LIST: return "LIST";
        case QoreAOTValueTag::VT_HASH: return "HASH";
        case QoreAOTValueTag::VT_NUMBER: return "NUMBER";
        case QoreAOTValueTag::VT_BINARY: return "BINARY";
        case QoreAOTValueTag::VT_OPAQUE_DEFAULT: return "OPAQUE_DEFAULT";
        case QoreAOTValueTag::VT_ABS_DATE_REGION: return "ABS_DATE_REGION";
        case QoreAOTValueTag::VT_ENUM: return "ENUM";
        case QoreAOTValueTag::VT_NEW_OBJECT: return "NEW_OBJECT";
        case QoreAOTValueTag::VT_CONST_REF: return "CONST_REF";
        case QoreAOTValueTag::VT_NEW_COMPLEX_DEFAULT: return "NEW_COMPLEX_DEFAULT";
        case QoreAOTValueTag::VT_EXPR_TREE: return "EXPR_TREE";
        case QoreAOTValueTag::VT_EXPR_NATIVE: return "EXPR_NATIVE";
        case QoreAOTValueTag::VT_PLUGIN_INSTANCE: return "PLUGIN_INSTANCE";
        case QoreAOTValueTag::VT_CHAR: return "CHAR";
    }
    return "UNKNOWN";
}

struct AOTDefaultDumpSummary {
    struct Detail {
        std::string category;
        std::string owner;
        std::string name;
        uint8_t tag = 0;
        uint8_t root_kind = 0;
        uint32_t blob_size = 0;
    };

    uint64_t defaults = 0;
    std::map<uint8_t, uint64_t> top_value_tags;
    std::map<uint8_t, uint64_t> all_value_tags;
    std::vector<Detail> expr_tree_details;
};

static bool dump_skip_serialized_value(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, AOTDefaultDumpSummary& summary,
        std::string& error, bool top_level, const char* category,
        const std::string& owner, const std::string& name);

static bool dump_skip_serialized_value_args(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, uint32_t count,
        AOTDefaultDumpSummary& summary, std::string& error) {
    for (uint32_t i = 0; i < count; ++i) {
        if (!dump_skip_serialized_value(reader, p, end, summary, error, false,
                "", "", "")) {
            return false;
        }
    }
    return true;
}

static bool dump_skip_container_value_type(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end) {
    if ((reader.getHeader().feature_flags & QORE_AOT_FEAT_TYPED_VALUE_CONTAINERS) == 0) {
        return true;
    }
    uint8_t kind = 0;
    if (!dump_read_u8(p, end, kind)) {
        return false;
    }
    return kind == static_cast<uint8_t>(QoreAOTContainerValueType::Plain)
        || dump_skip_len_string_ref(reader, p, end);
}

static bool dump_skip_serialized_value(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end, AOTDefaultDumpSummary& summary,
        std::string& error, bool top_level, const char* category,
        const std::string& owner, const std::string& name) {
    uint8_t tag = 0;
    if (!dump_read_u8(p, end, tag)) {
        error = "truncated serialized value tag";
        return false;
    }

    ++summary.all_value_tags[tag];
    if (top_level) {
        ++summary.defaults;
        ++summary.top_value_tags[tag];
    }

    auto fail = [&](const char* msg) {
        error = msg;
        return false;
    };

    switch (static_cast<QoreAOTValueTag>(tag)) {
        case QoreAOTValueTag::VT_NOTHING:
        case QoreAOTValueTag::VT_NULL:
        case QoreAOTValueTag::VT_OPAQUE_DEFAULT:
            return true;

        case QoreAOTValueTag::VT_BOOL:
            return dump_skip_bytes(p, end, 1) || fail("truncated bool value");

        case QoreAOTValueTag::VT_CHAR:
            return dump_skip_bytes(p, end, 4) || fail("truncated char value");

        case QoreAOTValueTag::VT_INT64:
        case QoreAOTValueTag::VT_FLOAT64:
            return dump_skip_bytes(p, end, 8) || fail("truncated 64-bit value");

        case QoreAOTValueTag::VT_STRING:
        case QoreAOTValueTag::VT_NUMBER:
        case QoreAOTValueTag::VT_CONST_REF:
            return dump_skip_len_string_ref(reader, p, end)
                || fail("truncated string reference value");

        case QoreAOTValueTag::VT_ABS_DATE:
            return dump_skip_bytes(p, end, 16) || fail("truncated absolute date value");

        case QoreAOTValueTag::VT_REL_DATE:
            return dump_skip_bytes(p, end, 56) || fail("truncated relative date value");

        case QoreAOTValueTag::VT_ABS_DATE_REGION:
            return (dump_skip_bytes(p, end, 8) && dump_skip_len_string_ref(reader, p, end))
                || fail("truncated regional absolute date value");

        case QoreAOTValueTag::VT_BINARY: {
            uint32_t size = 0;
            return (dump_read_u32(p, end, size) && dump_skip_bytes(p, end, size))
                || fail("truncated binary value");
        }

        case QoreAOTValueTag::VT_PLUGIN_INSTANCE: {
            if (!dump_skip_bytes(p, end, 8)) {
                return fail("truncated plugin value instance header");
            }
            uint32_t payload_size = 0;
            return (dump_read_u32(p, end, payload_size)
                    && dump_skip_bytes(p, end, payload_size))
                || fail("truncated plugin value payload");
        }

        case QoreAOTValueTag::VT_LIST: {
            uint32_t count = 0;
            return dump_skip_container_value_type(reader, p, end)
                && dump_read_u32(p, end, count)
                && dump_skip_serialized_value_args(reader, p, end, count, summary, error);
        }

        case QoreAOTValueTag::VT_HASH: {
            uint32_t count = 0;
            if (!dump_skip_container_value_type(reader, p, end)
                    || !dump_read_u32(p, end, count)) {
                return fail("truncated hash value");
            }
            for (uint32_t i = 0; i < count; ++i) {
                if (!dump_skip_string_ref(reader, p, end)
                        || !dump_skip_serialized_value(reader, p, end, summary, error,
                            false, "", "", "")) {
                    if (error.empty()) {
                        error = "truncated hash entry";
                    }
                    return false;
                }
            }
            return true;
        }

        case QoreAOTValueTag::VT_ENUM:
            return (dump_skip_len_string_ref(reader, p, end)
                    && dump_skip_len_string_ref(reader, p, end))
                || fail("truncated enum value");

        case QoreAOTValueTag::VT_NEW_OBJECT: {
            uint32_t nargs = 0;
            return dump_skip_len_string_ref(reader, p, end)
                && dump_read_u32(p, end, nargs)
                && dump_skip_serialized_value_args(reader, p, end, nargs, summary, error);
        }

        case QoreAOTValueTag::VT_NEW_COMPLEX_DEFAULT: {
            uint32_t nargs = 0;
            uint8_t kind = 0;
            return dump_read_u8(p, end, kind)
                && (kind != 3
                    || (reader.getHeader().feature_flags & QORE_AOT_FEAT_COMPLEX_BUFFER_INIT_KIND) == 0
                    || dump_skip_bytes(p, end, 1))
                && dump_skip_len_string_ref(reader, p, end)
                && dump_read_u32(p, end, nargs)
                && dump_skip_serialized_value_args(reader, p, end, nargs, summary, error);
        }

        case QoreAOTValueTag::VT_EXPR_TREE: {
            uint32_t blob_size = 0;
            if (!dump_read_u32(p, end, blob_size)) {
                return fail("truncated expression tree size");
            }
            if (!dump_need(p, end, blob_size)) {
                return fail("expression tree blob exceeds section bounds");
            }
            if (top_level) {
                summary.expr_tree_details.push_back({
                    category ? category : "",
                    owner,
                    name,
                    tag,
                    blob_size ? static_cast<uint8_t>(*p) : static_cast<uint8_t>(0),
                    blob_size,
                });
            }
            p += blob_size;
            return true;
        }

        case QoreAOTValueTag::VT_EXPR_NATIVE: {
            uint32_t blob_size = 0;
            if (!dump_read_u32(p, end, blob_size)) {
                return fail("truncated native expression size");
            }
            if (!dump_need(p, end, blob_size)) {
                return fail("native expression blob exceeds section bounds");
            }
            const uint8_t* blob_end = p + blob_size;
            AOTSlotMapDumpSummary expr_summary;
            AOTDumpExprContext expr_ctx;
            bool ok = dump_skip_inline_expr(reader, p, blob_end, expr_summary,
                "default", expr_ctx);
            if (!ok || p != blob_end) {
                p = blob_end;
                return fail("malformed native default expression");
            }
            return true;
        }
    }

    error = "unknown serialized value tag " + std::to_string(static_cast<unsigned>(tag));
    return false;
}

static bool dump_skip_serialized_value_no_summary(const QoreAOTBinaryReader& reader,
        const uint8_t*& p, const uint8_t* end) {
    AOTDefaultDumpSummary summary;
    std::string error;
    return dump_skip_serialized_value(reader, p, end, summary, error, false,
        "", "", "");
}

static std::string dump_owner_name(const char* preferred, const char* fallback) {
    if (preferred && *preferred) {
        return preferred;
    }
    if (fallback && *fallback) {
        return fallback;
    }
    return "(unnamed)";
}

static bool dump_scan_class_defaults(const QoreAOTBinaryReader& reader,
        AOTDefaultDumpSummary& summary, std::string& error) {
    const QoreAOTSectionHeader* sec = reader.findSection(QoreAOTSectionType::CLASSES);
    if (!sec) {
        return true;
    }
    const uint8_t* p = reader.getSectionData(*sec);
    if (!p) {
        error = "invalid CLASSES section";
        return false;
    }
    const uint8_t* end = p + sec->size;

    uint32_t count = 0;
    if (!dump_read_u32(p, end, count)) {
        error = "truncated CLASSES header";
        return false;
    }
    const bool has_const_pending_flag =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_CONST_PENDING) != 0;
    const bool has_class_hash =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_CLASS_HASH) != 0;
    const bool has_class_injection =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_CLASS_INJECTION) != 0;
    const bool has_class_type_params =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_CLASS_TYPE_PARAMS) != 0;
    const bool has_type_param_defaults =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_TYPE_PARAM_DEFAULTS) != 0;
    const bool has_type_param_bounds =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_TYPE_PARAM_BOUNDS) != 0;
    const bool has_class_param_bases =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_CLASS_PARAM_BASES) != 0;

    for (uint32_t i = 0; i < count; ++i) {
        const char* name = nullptr;
        const char* path = nullptr;
        if (!dump_skip_string_ref(reader, p, end, &name)
                || !dump_skip_string_ref(reader, p, end, &path)
                || !dump_skip_bytes(p, end, 4 + 2 + 8)) {
            error = "truncated class header";
            return false;
        }
        std::string owner = dump_owner_name(path, name);
        if (has_class_hash && !dump_skip_bytes(p, end, 1 + SH_SIZE)) {
            error = "truncated class signature hash";
            return false;
        }
        if (has_class_injection && !dump_skip_string_ref(reader, p, end)) {
            error = "truncated class injection target";
            return false;
        }
        if (has_class_type_params) {
            uint32_t type_param_count = 0;
            if (!dump_read_u32(p, end, type_param_count)) {
                error = "truncated class type parameter count";
                return false;
            }
            for (uint32_t j = 0; j < type_param_count; ++j) {
                if (j && !(j % 100) && qcc_check_cancel("AOT class type parameter dump")) {
                    error = "operation cancelled during AOT class type parameter dump";
                    return false;
                }
                if (!dump_skip_string_ref(reader, p, end)) {
                    error = "truncated class type parameter entry";
                    return false;
                }
                if (has_type_param_defaults) {
                    uint8_t has_default = 0;
                    if (!dump_read_u8(p, end, has_default)
                            || (has_default && !dump_skip_string_ref(reader, p, end))) {
                        error = "truncated class type parameter default";
                        return false;
                    }
                }
                if (has_type_param_bounds) {
                    uint8_t has_bound = 0;
                    if (!dump_read_u8(p, end, has_bound)
                            || (has_bound && !dump_skip_string_ref(reader, p, end))) {
                        error = "truncated class type parameter bound";
                        return false;
                    }
                }
            }
        }

        uint32_t num_bases = 0;
        if (!dump_read_u32(p, end, num_bases)) {
            error = "truncated class base count";
            return false;
        }
        for (uint32_t j = 0; j < num_bases; ++j) {
            if (!dump_skip_string_ref(reader, p, end) || !dump_skip_bytes(p, end, 2)) {
                error = "truncated class base entry";
                return false;
            }
            if (has_class_param_bases && !dump_skip_string_ref(reader, p, end)) {
                error = "truncated class parameterized base type";
                return false;
            }
        }
        // the class-flags byte (QORE_AOT_CLASS_FLAGS_VERSION)
        if (reader.getHeader().version >= QORE_AOT_CLASS_FLAGS_VERSION && !dump_skip_bytes(p, end, 1)) {
            error = "truncated class flags";
            return false;
        }

        uint32_t num_members = 0;
        if (!dump_read_u32(p, end, num_members)) {
            error = "truncated class member count";
            return false;
        }
        for (uint32_t j = 0; j < num_members; ++j) {
            const char* mname = nullptr;
            if (!dump_skip_string_ref(reader, p, end, &mname)
                    || !dump_skip_string_ref(reader, p, end)
                    || !dump_skip_bytes(p, end, 3)) {
                error = "truncated class member entry";
                return false;
            }
            uint8_t has_default = *(p - 1);
            if (has_default && !dump_skip_serialized_value(reader, p, end, summary,
                    error, true, "instance member", owner, dump_owner_name(mname, nullptr))) {
                return false;
            }
        }

        uint32_t num_static = 0;
        if (!dump_read_u32(p, end, num_static)) {
            error = "truncated static member count";
            return false;
        }
        for (uint32_t j = 0; j < num_static; ++j) {
            const char* mname = nullptr;
            if (!dump_skip_string_ref(reader, p, end, &mname)
                    || !dump_skip_string_ref(reader, p, end)
                    || !dump_skip_bytes(p, end, 2)) {
                error = "truncated static member entry";
                return false;
            }
            uint8_t has_default = *(p - 1);
            if (has_default && !dump_skip_serialized_value(reader, p, end, summary,
                    error, true, "static member", owner, dump_owner_name(mname, nullptr))) {
                return false;
            }
        }

        uint32_t num_consts = 0;
        if (!dump_read_u32(p, end, num_consts)) {
            error = "truncated class constant count";
            return false;
        }
        for (uint32_t j = 0; j < num_consts; ++j) {
            const char* cname = nullptr;
            if (!dump_skip_string_ref(reader, p, end, &cname)
                    || !dump_skip_string_ref(reader, p, end)
                    || !dump_skip_bytes(p, end, has_const_pending_flag ? 2 : 1)) {
                error = "truncated class constant entry";
                return false;
            }
            if (!dump_skip_serialized_value(reader, p, end, summary, error, true,
                    "class constant", owner, dump_owner_name(cname, nullptr))) {
                return false;
            }
        }
    }

    return true;
}

static bool dump_scan_hashdecl_defaults(const QoreAOTBinaryReader& reader,
        AOTDefaultDumpSummary& summary, std::string& error) {
    const QoreAOTSectionHeader* sec = reader.findSection(QoreAOTSectionType::HASHDECLS);
    if (!sec) {
        return true;
    }
    const uint8_t* p = reader.getSectionData(*sec);
    if (!p) {
        error = "invalid HASHDECLS section";
        return false;
    }
    const uint8_t* end = p + sec->size;

    uint32_t count = 0;
    if (!dump_read_u32(p, end, count)) {
        error = "truncated HASHDECLS header";
        return false;
    }
    const bool has_hashdecl_type_params =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_HASHDECL_TYPE_PARAMS) != 0;
    const bool has_type_param_defaults =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_TYPE_PARAM_DEFAULTS) != 0;
    const bool has_type_param_bounds =
        (reader.getHeader().feature_flags & QORE_AOT_FEAT_TYPE_PARAM_BOUNDS) != 0;

    for (uint32_t i = 0; i < count; ++i) {
        const char* name = nullptr;
        const char* path = nullptr;
        if (!dump_skip_string_ref(reader, p, end, &name)
                || !dump_skip_string_ref(reader, p, end, &path)
                || !dump_skip_bytes(p, end, 4 + 2)
                || !dump_skip_string_ref(reader, p, end)) {
            error = "truncated hashdecl header";
            return false;
        }
        std::string owner = dump_owner_name(path, name);

        if (has_hashdecl_type_params) {
            uint16_t type_param_count = 0;
            if (!dump_read_u16(p, end, type_param_count)) {
                error = "truncated hashdecl type parameter count";
                return false;
            }
            for (uint16_t j = 0; j < type_param_count; ++j) {
                if (j && !(j % 100) && qcc_check_cancel("AOT hashdecl type parameter dump")) {
                    error = "operation cancelled during AOT hashdecl type parameter dump";
                    return false;
                }
                if (!dump_skip_string_ref(reader, p, end)) {
                    error = "truncated hashdecl type parameter entry";
                    return false;
                }
                if (has_type_param_defaults) {
                    uint8_t has_default = 0;
                    if (!dump_read_u8(p, end, has_default)
                            || (has_default && !dump_skip_string_ref(reader, p, end))) {
                        error = "truncated hashdecl type parameter default";
                        return false;
                    }
                }
                if (has_type_param_bounds) {
                    uint8_t has_bound = 0;
                    if (!dump_read_u8(p, end, has_bound)
                            || (has_bound && !dump_skip_string_ref(reader, p, end))) {
                        error = "truncated hashdecl type parameter bound";
                        return false;
                    }
                }
            }
        }

        uint32_t num_members = 0;
        if (!dump_read_u32(p, end, num_members)) {
            error = "truncated hashdecl member count";
            return false;
        }
        for (uint32_t j = 0; j < num_members; ++j) {
            const char* mname = nullptr;
            if (!dump_skip_string_ref(reader, p, end, &mname)
                    || !dump_skip_string_ref(reader, p, end)) {
                error = "truncated hashdecl member entry";
                return false;
            }
            uint8_t has_default = 0;
            if (!dump_read_u8(p, end, has_default)) {
                error = "truncated hashdecl member default flag";
                return false;
            }
            if (has_default && !dump_skip_serialized_value(reader, p, end, summary,
                    error, true, "hashdecl member", owner, dump_owner_name(mname, nullptr))) {
                return false;
            }
        }
    }

    return true;
}

static bool dump_scan_constant_defaults(const QoreAOTBinaryReader& reader,
        AOTDefaultDumpSummary& summary, std::string& error) {
    const QoreAOTSectionHeader* sec = reader.findSection(QoreAOTSectionType::CONSTANTS);
    if (!sec) {
        return true;
    }
    const uint8_t* p = reader.getSectionData(*sec);
    if (!p) {
        error = "invalid CONSTANTS section";
        return false;
    }
    const uint8_t* end = p + sec->size;

    uint32_t count = 0;
    if (!dump_read_u32(p, end, count)) {
        error = "truncated CONSTANTS header";
        return false;
    }
    for (uint32_t i = 0; i < count; ++i) {
        const char* name = nullptr;
        if (!dump_skip_string_ref(reader, p, end, &name)
                || !dump_skip_string_ref(reader, p, end)
                || !dump_skip_bytes(p, end, 4 + 3)) {
            error = "truncated constant entry";
            return false;
        }
        if (!dump_skip_serialized_value(reader, p, end, summary, error, true,
                "constant", "", dump_owner_name(name, nullptr))) {
            return false;
        }
    }

    return true;
}

static void print_aot_default_summary(const QoreAOTBinaryReader& reader) {
    AOTDefaultDumpSummary summary;
    std::string error;
    if (!dump_scan_class_defaults(reader, summary, error)
            || !dump_scan_hashdecl_defaults(reader, summary, error)
            || !dump_scan_constant_defaults(reader, summary, error)) {
        printf("    serialized defaults: error: %s\n", error.c_str());
        return;
    }

    if (!summary.defaults) {
        printf("    serialized defaults: (none)\n");
        return;
    }

    auto count_tag = [&](QoreAOTValueTag tag) -> uint64_t {
        auto i = summary.top_value_tags.find(static_cast<uint8_t>(tag));
        return i == summary.top_value_tags.end() ? 0 : i->second;
    };

    printf("    serialized defaults: total=%llu expr-tree=%llu native-expr=%llu "
           "new-object=%llu complex-default=%llu enum=%llu const-ref=%llu\n",
        static_cast<unsigned long long>(summary.defaults),
        static_cast<unsigned long long>(count_tag(QoreAOTValueTag::VT_EXPR_TREE)),
        static_cast<unsigned long long>(count_tag(QoreAOTValueTag::VT_EXPR_NATIVE)),
        static_cast<unsigned long long>(count_tag(QoreAOTValueTag::VT_NEW_OBJECT)),
        static_cast<unsigned long long>(count_tag(QoreAOTValueTag::VT_NEW_COMPLEX_DEFAULT)),
        static_cast<unsigned long long>(count_tag(QoreAOTValueTag::VT_ENUM)),
        static_cast<unsigned long long>(count_tag(QoreAOTValueTag::VT_CONST_REF)));

    if (dump_sections) {
        printf("      top serialized default tags:\n");
        for (const auto& [tag, count] : summary.top_value_tags) {
            printf("        %-20s (%3u): %llu\n", dump_aot_value_tag_name(tag), tag,
                static_cast<unsigned long long>(count));
        }
    }

    if (!summary.expr_tree_details.empty()) {
        printf("      EXPR_TREE defaults:\n");
        size_t limit = dump_sections ? summary.expr_tree_details.size()
            : std::min<size_t>(summary.expr_tree_details.size(), 8);
        for (size_t i = 0; i < limit; ++i) {
            const auto& detail = summary.expr_tree_details[i];
            printf("        %s %s::%s root=%s (%u) size=%u\n",
                detail.category.c_str(),
                detail.owner.c_str(),
                detail.name.c_str(),
                dump_aot_expr_node_kind_name(detail.root_kind),
                detail.root_kind,
                detail.blob_size);
        }
        if (summary.expr_tree_details.size() > limit) {
            printf("        ... +%zu\n", summary.expr_tree_details.size() - limit);
        }
    }
}

static void print_aot_symbol_record(const QoreAOTSymbolIndexRecord& rec, bool native_record = false) {
    printf("      %-13s %s", qoreAOTSymbolKindName(rec.kind),
        rec.qore_path.empty() ? "(none)" : rec.qore_path.c_str());
    if (!rec.visibility.empty()) {
        printf(" visibility=%s", rec.visibility.c_str());
    }
    if (!rec.source_file.empty()) {
        printf(" source=%s", rec.source_file.c_str());
    }
    if (!rec.signature_hash.empty()) {
        printf(" sig=%s", rec.signature_hash.c_str());
    }
    if (!rec.declaration_hash.empty()) {
        printf(" decl=%s", rec.declaration_hash.c_str());
    }
    if (!rec.value_hash.empty()) {
        printf(" value=%s", rec.value_hash.c_str());
    }
    if (!rec.body_contract_hash.empty()) {
        printf(" body=%s", rec.body_contract_hash.c_str());
    }
    if (!rec.native_symbol.empty()) {
        if (native_record) {
            printf(" %s->%s",
                (rec.flags & QORE_AOT_SYMBOL_FLAG_NATIVE_DEFINED) ? "defined" : "undefined",
                rec.native_symbol.c_str());
        } else {
            printf(" native=%s", rec.native_symbol.c_str());
        }
    }
    if (!rec.abi_kind.empty()) {
        printf(" abi=%s", rec.abi_kind.c_str());
    }
    if (rec.fast_entry_flags) {
        printf(" fast_flags=0x%x fast_params=%u fast_return=%u", rec.fast_entry_flags,
            rec.fast_entry_num_params, rec.fast_return_kind);
        if (!rec.fast_specialization_key.empty()) {
            printf(" fast_specialization=%s",
                rec.fast_specialization_key.c_str());
        }
        if (rec.scalar_leaf_kind) {
            printf(" scalar_leaf=%u:%u", rec.scalar_leaf_kind, rec.scalar_leaf_opcode);
        }
    }
    if (rec.dependency_class != QoreAOTDependencyClass::UNKNOWN) {
        printf(" dep=%s", qoreAOTDependencyClassName(rec.dependency_class));
    }
    if (!rec.consumer_source_file.empty()) {
        printf(" consumer=%s", rec.consumer_source_file.c_str());
    }
    if (!rec.provider_source_file.empty()) {
        printf(" provider=%s", rec.provider_source_file.c_str());
    }
    if (!rec.body_dependency_files.empty()) {
        printf(" body_deps=%zu", rec.body_dependency_files.size());
    }
    if (rec.metadata_slot != UINT32_MAX) {
        printf(" slot=%u", rec.metadata_slot);
    }
    printf("\n");
}

static bool dump_aot_symbol_index_check_cancel(size_t ordinal, const char* operation) {
    if (ordinal && !(ordinal % 100) && qcc_check_cancel(operation)) {
        printf("      cancelled during %s\n", operation ? operation : "AOT symbol-index dump");
        return false;
    }
    return true;
}

static void print_aot_symbol_index(const QoreAOTBinaryReader& reader) {
    QoreAOTSymbolIndex index;
    std::string error;
    if (!readSymbolIndex(reader, index, error)) {
        printf("    symbol index: error: %s\n", error.c_str());
        return;
    }

    if (!index.version) {
        printf("    symbol index: not present\n");
        return;
    }

    printf("    symbol index: version=%u defined=%zu imported=%zu native=%zu\n",
        index.version, index.defined.size(), index.imported.size(), index.native.size());
    if (!dump_symbols) {
        return;
    }

    if (!index.context.empty()) {
        printf("    AOT symbol context:\n");
        for (size_t i = 0; i < index.context.size(); ++i) {
            if (!dump_aot_symbol_index_check_cancel(i, "AOT symbol-index context dump")) {
                return;
            }
            const auto& [key, value] = index.context[i];
            printf("      %s: %s\n", key.c_str(), value.c_str());
        }
    }

    printf("    AOT defined Qore symbols:%s\n", index.defined.empty() ? " (none)" : "");
    for (size_t i = 0; i < index.defined.size(); ++i) {
        if (!dump_aot_symbol_index_check_cancel(i, "AOT symbol-index definition dump")) {
            return;
        }
        print_aot_symbol_record(index.defined[i]);
    }

    printf("    AOT imported Qore symbols:%s\n", index.imported.empty() ? " (none)" : "");
    for (size_t i = 0; i < index.imported.size(); ++i) {
        if (!dump_aot_symbol_index_check_cancel(i, "AOT symbol-index import dump")) {
            return;
        }
        print_aot_symbol_record(index.imported[i]);
    }

    printf("    AOT native symbols:%s\n", index.native.empty() ? " (none)" : "");
    for (size_t i = 0; i < index.native.size(); ++i) {
        if (!dump_aot_symbol_index_check_cancel(i, "AOT symbol-index native dump")) {
            return;
        }
        print_aot_symbol_record(index.native[i], true);
    }
}

static bool dump_aot_call_relocations_check_cancel(size_t ordinal, const char* operation) {
    if (ordinal && !(ordinal % 100) && qcc_check_cancel(operation)) {
        printf("      cancelled during %s\n", operation ? operation : "AOT call-relocation dump");
        return false;
    }
    return true;
}

static void print_aot_call_relocations(const QoreAOTBinaryReader& reader) {
    QoreAOTCallRelocations relocs;
    std::string error;
    if (!readCallRelocations(reader, relocs, error)) {
        printf("    call relocations: error: %s\n", error.c_str());
        return;
    }

    if (!relocs.version) {
        printf("    call relocations: not present\n");
        return;
    }

    printf("    call relocations: version=%u records=%zu\n",
        relocs.version, relocs.records.size());
    if (!dump_symbols) {
        return;
    }

    for (size_t i = 0; i < relocs.records.size(); ++i) {
        if (!dump_aot_call_relocations_check_cancel(i, "AOT call-relocation dump")) {
            return;
        }
        const QoreAOTCallRelocationRecord& rec = relocs.records[i];
        printf("      %-13s %s func=%s slot=%u strict=%s",
            qoreAOTCallRelocationTargetKindName(rec.target_kind),
            rec.qore_path.empty() ? "(none)" : rec.qore_path.c_str(),
            rec.function_name.c_str(), rec.expr_slot,
            rec.strictness == QoreAOTCallRelocationStrictness::REQUIRED ? "required" : "optional");
        if (!rec.native_symbol.empty()) {
            printf(" native=%s", rec.native_symbol.c_str());
        }
        if (!rec.signature_hash.empty()) {
            printf(" sig=%s", rec.signature_hash.c_str());
        }
        if (!rec.declaration_hash.empty()) {
            printf(" decl=%s", rec.declaration_hash.c_str());
        }
        if (!rec.fallback_descriptor.empty()) {
            printf(" fallback=%s", rec.fallback_descriptor.c_str());
        }
        printf("\n");
    }
}

static void dump_aot_metadata_blob(const AOTDumpMetadataBlob& blob, size_t index) {
    QoreAOTBinaryReader reader;
    std::string error;
    if (!reader.open(blob.bytes.data(), static_cast<uint32_t>(blob.bytes.size()), error)) {
        printf("  AOT metadata #%zu: invalid: %s\n", index, error.c_str());
        return;
    }

    const QoreAOTBinaryHeader& hdr = reader.getHeader();
    const char* label = reader.getLabel();
    printf("  AOT metadata #%zu (%s):\n", index, blob.source.c_str());
    const char* compression_name = hdr.compression == QORE_AOT_COMPRESSION_ZSTD ? "zstd"
        : (hdr.compression == QORE_AOT_COMPRESSION_ZLIB ? "zlib"
        : (hdr.compression == QORE_AOT_COMPRESSION_SECTIONED_ZSTD ? "sectioned-zstd" : nullptr));
    printf("    size: %zu bytes%s", blob.bytes.size(), compression_name ? " compressed" : "");
    if (compression_name) {
        printf(" (%s)", compression_name);
    }
    printf("\n");
    printf("    label: %s\n", label ? label : "");
    printf("    kind:%s%s\n",
        (hdr.flags & QORE_AOT_FLAG_IS_MODULE) ? " module" : "",
        (hdr.flags & QORE_AOT_FLAG_HAS_TOPLEVEL) ? " toplevel" : "");
    printf("    format: %u (current %u)%s\n", hdr.version, QORE_AOT_BINARY_VERSION,
        hdr.version == QORE_AOT_BINARY_VERSION ? "" : " MISMATCH");
    printf("    compiled qore: %u.%u.%u (runtime %s)\n",
        hdr.qore_version_major, hdr.qore_version_minor, hdr.qore_version_patch,
        qore_version_string);
    printf("    parse options: lo=0x%016llx hi=0x%016llx\n",
        static_cast<unsigned long long>(hdr.parse_options_lo),
        static_cast<unsigned long long>(hdr.parse_options_hi));
    printf("    source hash: 0x%016llx\n",
        static_cast<unsigned long long>(hdr.source_hash));
    printf("    max opcode: %u (runtime %u)%s\n", hdr.max_opcode_id,
        QORE_IR_MAX_OPCODE, hdr.max_opcode_id <= QORE_IR_MAX_OPCODE ? "" : " MISMATCH");
    print_aot_feature_flags(hdr.feature_flags);

    std::vector<std::string> deps;
    if (readDependencies(blob.bytes.data(), static_cast<uint32_t>(blob.bytes.size()), deps, error)) {
        print_string_list("dependencies", deps);
    } else {
        printf("    dependencies: error: %s\n", error.c_str());
        error.clear();
    }

    std::vector<std::string> imports;
    bool imports_present = false;
    if (readImportDependencies(reader, imports, imports_present, error)) {
        if (imports_present) {
            print_string_list("imports", imports);
        } else {
            printf("    imports: (legacy: all dependencies)\n");
        }
    } else {
        printf("    imports: error: %s\n", error.c_str());
        error.clear();
    }

    std::vector<std::string> reexports;
    if (readReexportModules(blob.bytes.data(), static_cast<uint32_t>(blob.bytes.size()), reexports, error)) {
        print_string_list("reexports", reexports);
    } else {
        printf("    reexports: error: %s\n", error.c_str());
        error.clear();
    }

    std::vector<std::string> prepended;
    std::vector<std::string> appended;
    if (readModulePathLists(reader, prepended, appended, error)) {
        print_string_list("prepend module paths", prepended);
        print_string_list("append module paths", appended);
    } else {
        printf("    module paths: error: %s\n", error.c_str());
        error.clear();
    }

    std::vector<AOTModuleCommand> module_commands;
    if (readModuleCommands(reader, module_commands, error)) {
        print_module_commands(module_commands);
    } else {
        printf("    module commands: error: %s\n", error.c_str());
        error.clear();
    }

    std::string exec_class;
    if (readProgramMetadata(blob.bytes.data(), static_cast<uint32_t>(blob.bytes.size()), exec_class, error)
            && !exec_class.empty()) {
        printf("    exec class: %s\n", exec_class.c_str());
    } else if (!error.empty()) {
        printf("    program metadata: error: %s\n", error.c_str());
        error.clear();
    }

    std::vector<std::pair<std::string, std::string>> build_info;
    if (readBuildInfo(reader, build_info, error)) {
        if (!build_info.empty()) {
            printf("    build info:\n");
            for (const auto& [key, value] : build_info) {
                printf("      %s: %s\n", key.c_str(), value.c_str());
            }
        }
    } else {
        printf("    build info: error: %s\n", error.c_str());
        error.clear();
    }

    std::vector<QoreAOTUnrunTopLevelStatement> unrun_top_level;
    if (readAOTUnrunTopLevelCode(reader, unrun_top_level, error)) {
        if (!unrun_top_level.empty()) {
            printf("    unrun top-level code:\n");
            for (const QoreAOTUnrunTopLevelStatement& stmt : unrun_top_level) {
                printf("      %s:%d: %s\n", stmt.file.c_str(), static_cast<int>(stmt.line), stmt.description.c_str());
            }
        }
    } else {
        printf("    unrun top-level code: error: %s\n", error.c_str());
        error.clear();
    }

    QoreAOTSourceStatFingerprint source_fingerprint;
    if (readAOTSourceStatFingerprint(reader, source_fingerprint)) {
        printf("    source stat fingerprint:\n");
        printf("      source-size: %llu\n", static_cast<unsigned long long>(source_fingerprint.size));
        printf("      source-mtime-ns: %llu\n",
            static_cast<unsigned long long>(source_fingerprint.mtime_ns));
    }

    print_aot_slot_map_summary(reader);
    print_aot_default_summary(reader);
    print_aot_symbol_index(reader);
    print_aot_call_relocations(reader);

    printf("    sections: %u\n", reader.getSectionCount());
    if (dump_sections) {
        for (uint32_t i = 0; i < reader.getSectionCount(); ++i) {
            const QoreAOTSectionHeader* sec = reader.getSection(i);
            if (!sec) {
                continue;
            }
            printf("      %-20s type=%u offset=%u size=%u\n",
                aot_section_type_name(sec->type), sec->type, sec->offset, sec->size);
        }
    }
}

struct AOTDumpSymbolRow {
    std::string name;
    std::string section;
    uint64_t value = 0;
    uint64_t size = 0;
    char kind = '?';
    bool qore_relevant = false;
};

static std::string hex64_string(uint64_t value);

static std::vector<AOTDumpSymbolRow> collect_symbol_rows(const llvm::object::ObjectFile& obj) {
    std::map<std::string, uint64_t> size_by_key;
    for (const auto& [sym, size] : llvm::object::computeSymbolSizes(obj)) {
        size_by_key[symbol_key(obj, sym)] = size;
    }

    std::vector<AOTDumpSymbolRow> rows;
    for (const llvm::object::SymbolRef& sym : obj.symbols()) {
        auto name_or = sym.getName();
        if (!name_or) {
            llvm::consumeError(name_or.takeError());
            continue;
        }
        AOTDumpSymbolRow row;
        row.name = name_or->str();
        row.section = symbol_section_name(obj, sym);
        row.value = symbol_value(sym);
        row.kind = symbol_kind(sym);
        row.qore_relevant = is_qore_relevant_symbol(row.name);
        auto size_it = size_by_key.find(symbol_key(obj, sym));
        if (size_it != size_by_key.end()) {
            row.size = size_it->second;
        }
        rows.push_back(std::move(row));
    }
    return rows;
}

static bool string_has_suffix(const std::string& s, const char* suffix) {
    size_t n = s.size();
    size_t e = std::strlen(suffix);
    return n >= e && std::strcmp(s.c_str() + n - e, suffix) == 0;
}

static bool string_has_prefix(const std::string& s, const char* prefix) {
    size_t n = std::strlen(prefix);
    return s.size() >= n && std::memcmp(s.data(), prefix, n) == 0;
}

struct QOLinkInputInfo {
    std::string path;
    std::string object_hash;
    uint64_t object_size = 0;
    std::vector<std::string> source_text;
    std::string register_symbol;
    QoreAOTSymbolIndex index;
    std::vector<std::string> dependencies;
    std::vector<std::string> module_path_prepend;
    std::vector<std::string> module_path_append;
    std::vector<AOTModuleCommand> module_commands;
    std::vector<std::string> native_symbols;
    std::vector<QoreAOTCallRelocationRecord> call_relocations;
};

struct QOLinkIssue {
    std::string consumer;
    std::string path;
    std::string dependency_class;
    std::string expected;
    std::vector<std::string> providers;
};

struct QOLinkCallRelocation {
    std::string consumer;
    std::string function_name;
    uint32_t expr_slot = UINT32_MAX;
    std::string target_kind;
    std::string path;
    std::string path_scope;
    std::string dependency_class;
    std::string resolution;
    std::string reason;
    std::string expected;
    std::string provider_kind;
    std::string provider_source;
    std::string native_symbol;
    std::string fallback_descriptor;
    std::vector<std::string> providers;
};

struct QOLinkPlan {
    std::vector<std::string> provided_qore_symbols;
    std::vector<std::string> native_symbols;
    std::vector<std::string> external_dependencies;
    std::vector<std::string> module_path_prepend;
    std::vector<std::string> module_path_append;
    std::vector<AOTModuleCommand> module_commands;
    std::vector<QOLinkIssue> resolved_imports;
    std::vector<QOLinkIssue> unresolved_imports;
    std::vector<QOLinkIssue> ambiguous_imports;
    std::vector<QOLinkIssue> hash_mismatches;
    std::vector<QOLinkCallRelocation> resolved_call_relocations;
    std::vector<QOLinkCallRelocation> unresolved_call_relocations;
    std::vector<QOLinkCallRelocation> ambiguous_call_relocations;
    std::vector<QOLinkCallRelocation> call_relocation_hash_mismatches;
};

using QOLinkProviderMap = std::map<std::string, std::vector<const QoreAOTSymbolIndexRecord*>>;

struct QOLinkProviderIndex {
    QOLinkProviderMap exact;
    QOLinkProviderMap raw_suffix;
    QOLinkProviderMap callable_suffix;
    QOLinkProviderMap callable_base_exact;
};

static void add_unique_string(std::vector<std::string>& out, std::set<std::string>& seen,
        const std::string& value) {
    if (!value.empty() && seen.insert(value).second) {
        out.push_back(value);
    }
}

static bool qo_link_check_cancel(size_t ordinal, const char* operation, std::string& error) {
    if (ordinal && !(ordinal % 100) && qcc_check_cancel(operation)) {
        error = "operation cancelled during ";
        error += operation ? operation : "AOT qo-link processing";
        return false;
    }
    return true;
}

//! Returns the object format's global-symbol prefix, or 0 if it has none.
/** Mach-O and 32-bit x86 COFF decorate every external symbol with a leading
    underscore, so the object symbol table spells the LLVM IR identifier
    `qore_x_script_register` as `_qore_x_script_register`.  ELF and 64-bit
    COFF use the symbol name verbatim.
*/
static char qo_object_global_symbol_prefix(const llvm::object::ObjectFile& obj) {
    if (obj.isMachO()) {
        return '_';
    }
    if (obj.isCOFF() && obj.getArch() == llvm::Triple::x86) {
        return '_';
    }
    return 0;
}

//! Collects the logical IR names of the `*_script_register` symbols defined by @p obj.
/** The names collected here are stored in QOLinkInputInfo::register_symbol,
    written to the `.qolink.json` link map, and handed to
    QoreAOT::compileScriptRegisterAggregate(), which treats them as LLVM IR
    identifiers and lets the target mangler decorate them again when the
    aggregate object is emitted.  The object-file spelling must therefore be
    normalized back to its logical form here, or the aggregate references
    `__qore_x_script_register` on Mach-O while the inputs define
    `_qore_x_script_register`, and the native link fails with undefined
    symbols.

    Only the qcc-generated `qore..._script_register` family is normalized;
    no other leading underscore is touched.

    Only defined *global* symbols qualify.  A registration entry point is by
    definition exported: the aggregate object emitted by
    QoreAOT::compileScriptRegisterAggregate() references it across a native
    link, so a local record can never satisfy it.  The distinction is not
    academic on Mach-O: the parallel-codegen path merges its partition objects
    with `ld -r`, and the Darwin linker writes a STABS debug map into the
    merged symbol table (N_SO/N_OSO/N_BNSYM/N_FUN/N_ENSYM).  The N_FUN record
    for the registration function carries the same name and address as the
    real `N_SECT|N_EXT` definition but is non-external, so accepting every
    defined record made a valid split-codegen object look like it exported the
    registration function twice and `--link-qo` rejected it with
    "input has multiple exported *_script_register symbols".
*/
static bool collect_qo_register_symbols(const llvm::object::ObjectFile& obj,
        std::vector<std::string>& register_symbols, std::string& error) {
    const char global_prefix = qo_object_global_symbol_prefix(obj);
    std::set<std::string> seen;
    size_t i = 0;
    for (const llvm::object::SymbolRef& sym : obj.symbols()) {
        if (!qo_link_check_cancel(i++, "AOT qo-link register-symbol scan", error)) {
            return false;
        }
        // the entry point must be an exported definition; local debug-map
        // records and undefined references are not registration functions
        uint32_t flags = symbol_flags(sym);
        if (!(flags & llvm::object::SymbolRef::SF_Global)
            || (flags & llvm::object::SymbolRef::SF_Undefined)) {
            continue;
        }
        auto name_or = sym.getName();
        if (!name_or) {
            llvm::consumeError(name_or.takeError());
            continue;
        }
        std::string name = name_or->str();
        if (!string_has_suffix(name, "_script_register")) {
            continue;
        }
        // strip the target decoration so the stored name is the logical
        // IR identifier the aggregate module must reference
        if (global_prefix && name.size() > 5 && name[0] == global_prefix
            && !name.compare(1, 4, "qore")) {
            name.erase(0, 1);
        }
        // defensive: an object format that lists the same exported
        // definition twice still contributes one logical registration name
        if (seen.insert(name).second) {
            register_symbols.push_back(std::move(name));
        }
    }
    return true;
}

static bool collect_qo_link_input(const char* path, QOLinkInputInfo& input,
        std::string& error) {
    input = QOLinkInputInfo();
    input.path = path;

    std::string contents;
    if (!read_file(path, contents)) {
        error = std::string("cannot read input object: ") + path;
        return false;
    }
    input.object_size = contents.size();
    input.object_hash = "xxh64:" + hex64_string(XXH64(contents.data(), contents.size(), 0));

    auto binary_or = llvm::object::createBinary(path);
    if (!binary_or) {
        error = "cannot read object file '" + std::string(path) + "': "
            + llvm::toString(binary_or.takeError());
        return false;
    }
    llvm::object::Binary* binary = binary_or->getBinary();
    auto* obj = llvm::dyn_cast<llvm::object::ObjectFile>(binary);
    if (!obj) {
        error = "input is not a relocatable object file: " + std::string(path);
        return false;
    }

    std::vector<std::string> register_symbols;
    if (!collect_qo_register_symbols(*obj, register_symbols, error)) {
        return false;
    }
    if (register_symbols.empty()) {
        error = "input has no exported *_script_register symbol: " + std::string(path);
        return false;
    }
    if (register_symbols.size() > 1) {
        error = "input has multiple exported *_script_register symbols: " + std::string(path);
        for (const std::string& sym : register_symbols) {
            error += " " + sym;
        }
        return false;
    }
    input.register_symbol = register_symbols.front();

    std::vector<AOTDumpMetadataBlob> blobs;
    std::set<std::string> seen_blobs;
    extract_aot_metadata_from_object(*obj, blobs, seen_blobs);
    scan_aot_metadata_blobs(contents, blobs, seen_blobs);
    if (blobs.empty()) {
        error = "input has no AOT metadata blob: " + std::string(path);
        return false;
    }

    bool have_index = false;
    std::set<std::string> source_seen;
    std::set<std::string> dep_seen;
    std::set<std::string> prepend_seen;
    std::set<std::string> append_seen;
    std::set<std::string> module_cmd_seen;
    std::set<std::string> native_seen;
    input.index.version = QORE_AOT_SYMBOL_INDEX_VERSION;

    for (size_t i = 0; i < blobs.size(); ++i) {
        if (i && !(i % 100) && qcc_check_cancel("AOT qo-link metadata scan")) {
            error = "operation cancelled during AOT qo-link metadata scan";
            return false;
        }
        QoreAOTBinaryReader reader;
        std::string read_error;
        if (!reader.open(blobs[i].bytes.data(), static_cast<uint32_t>(blobs[i].bytes.size()), read_error)) {
            error = "invalid AOT metadata in '" + std::string(path) + "': " + read_error;
            return false;
        }
        const char* label = reader.getLabel();
        if (label && *label) {
            add_unique_string(input.source_text, source_seen, label);
        }

        QoreAOTSymbolIndex index;
        if (!readSymbolIndex(reader, index, read_error)) {
            error = "invalid SYMBOL_INDEX in '" + std::string(path) + "': " + read_error;
            return false;
        }
        if (index.version) {
            have_index = true;
            input.index.context.insert(input.index.context.end(), index.context.begin(), index.context.end());
            input.index.defined.insert(input.index.defined.end(), index.defined.begin(), index.defined.end());
            input.index.imported.insert(input.index.imported.end(), index.imported.begin(), index.imported.end());
            input.index.native.insert(input.index.native.end(), index.native.begin(), index.native.end());
            for (size_t j = 0; j < index.native.size(); ++j) {
                if (!qo_link_check_cancel(j, "AOT qo-link native symbol collection", error)) {
                    return false;
                }
                const QoreAOTSymbolIndexRecord& rec = index.native[j];
                if (!rec.native_symbol.empty()) {
                    add_unique_string(input.native_symbols, native_seen, rec.native_symbol);
                }
            }
        }

        QoreAOTCallRelocations relocs;
        if (!readCallRelocations(reader, relocs, read_error)) {
            error = "invalid CALL_RELOCATIONS in '" + std::string(path) + "': " + read_error;
            return false;
        }
        if (relocs.version) {
            input.call_relocations.insert(input.call_relocations.end(),
                relocs.records.begin(), relocs.records.end());
        }

        std::vector<std::string> deps;
        if (!readDependencies(reader, deps, read_error)) {
            error = "invalid dependency metadata in '" + std::string(path) + "': " + read_error;
            return false;
        }
        for (size_t j = 0; j < deps.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link dependency collection", error)) {
                return false;
            }
            add_unique_string(input.dependencies, dep_seen, deps[j]);
        }

        std::vector<std::string> prepended;
        std::vector<std::string> appended;
        if (!readModulePathLists(reader, prepended, appended, read_error)) {
            error = "invalid module path metadata in '" + std::string(path) + "': " + read_error;
            return false;
        }
        for (size_t j = 0; j < prepended.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link module path collection", error)) {
                return false;
            }
            add_unique_string(input.module_path_prepend, prepend_seen, prepended[j]);
        }
        for (size_t j = 0; j < appended.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link module path collection", error)) {
                return false;
            }
            add_unique_string(input.module_path_append, append_seen, appended[j]);
        }

        std::vector<AOTModuleCommand> commands;
        if (!readModuleCommands(reader, commands, read_error)) {
            error = "invalid module command metadata in '" + std::string(path) + "': " + read_error;
            return false;
        }
        for (size_t j = 0; j < commands.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link module command collection", error)) {
                return false;
            }
            const AOTModuleCommand& cmd = commands[j];
            std::string key = cmd.module + "\n" + cmd.command;
            if (module_cmd_seen.insert(key).second) {
                input.module_commands.push_back(cmd);
            }
        }
    }

    if (!have_index) {
        error = "input has no SYMBOL_INDEX section: " + std::string(path);
        return false;
    }
    return true;
}

static bool is_owned_qore_provider(const QoreAOTSymbolIndexRecord& rec) {
    return !rec.qore_path.empty() && !rec.source_file.empty();
}

static bool is_optional_qo_import(const QoreAOTSymbolIndexRecord& rec) {
    return (rec.flags & QORE_AOT_SYMBOL_FLAG_OPTIONAL_IMPORT) != 0;
}

static bool is_deferred_callable_qo_import(const QoreAOTSymbolIndexRecord& rec) {
    return (rec.kind == QoreAOTSymbolKind::FUNCTION
            || rec.kind == QoreAOTSymbolKind::METHOD
            || rec.kind == QoreAOTSymbolKind::STATIC_METHOD
            || rec.kind == QoreAOTSymbolKind::CONSTRUCTOR)
        && rec.qore_path.find('(') == std::string::npos;
}

static std::string qo_link_strip_leading_colons(const std::string& path) {
    return string_has_prefix(path, "::") ? path.substr(2) : path;
}

static void qo_link_add_provider_candidate(QOLinkProviderMap& providers,
        const std::string& key, const QoreAOTSymbolIndexRecord* rec) {
    if (!key.empty()) {
        providers[key].push_back(rec);
    }
}

static void qo_link_add_suffix_keys(std::set<std::string>& keys, const std::string& path) {
    if (path.empty()) {
        return;
    }
    keys.insert(path);
    size_t pos = 0;
    while ((pos = path.find("::", pos)) != std::string::npos) {
        pos += 2;
        if (pos < path.size()) {
            keys.insert(path.substr(pos));
        }
    }
}

static void qo_link_index_raw_suffix(QOLinkProviderMap& providers,
        const QoreAOTSymbolIndexRecord* rec) {
    std::string stripped = qo_link_strip_leading_colons(rec->qore_path);
    size_t sig_pos = stripped.find('(');
    std::set<std::string> keys;
    if (sig_pos == std::string::npos) {
        qo_link_add_suffix_keys(keys, stripped);
    } else {
        std::string base = stripped.substr(0, sig_pos);
        std::string signature = stripped.substr(sig_pos);
        std::set<std::string> base_keys;
        qo_link_add_suffix_keys(base_keys, base);
        for (const std::string& key : base_keys) {
            keys.insert(key + signature);
        }
    }
    for (const std::string& key : keys) {
        qo_link_add_provider_candidate(providers, key, rec);
    }
}

static void qo_link_index_callable_suffix(QOLinkProviderMap& providers,
        const QoreAOTSymbolIndexRecord* rec) {
    std::string stripped = qo_link_strip_leading_colons(rec->qore_path);
    size_t sig_pos = stripped.find('(');
    if (sig_pos == std::string::npos) {
        qo_link_index_raw_suffix(providers, rec);
        return;
    }

    std::string base = stripped.substr(0, sig_pos);
    std::string signature = stripped.substr(sig_pos);
    std::set<std::string> base_keys;
    qo_link_add_suffix_keys(base_keys, base);
    for (const std::string& key : base_keys) {
        qo_link_add_provider_candidate(providers, key, rec);
        qo_link_add_provider_candidate(providers, key + signature, rec);
    }
}

static void qo_link_index_callable_base_exact(QOLinkProviderMap& providers,
        const QoreAOTSymbolIndexRecord* rec) {
    std::string stripped = qo_link_strip_leading_colons(rec->qore_path);
    size_t sig_pos = stripped.find('(');
    if (sig_pos != std::string::npos) {
        qo_link_add_provider_candidate(providers, stripped.substr(0, sig_pos), rec);
    }
}

static void qo_link_index_provider(QOLinkProviderIndex& index,
        const QoreAOTSymbolIndexRecord* rec) {
    index.exact[rec->qore_path].push_back(rec);
    qo_link_index_raw_suffix(index.raw_suffix, rec);
    qo_link_index_callable_suffix(index.callable_suffix, rec);
    qo_link_index_callable_base_exact(index.callable_base_exact, rec);
}

static void find_deferred_callable_qo_providers(
        const QOLinkProviderMap& providers,
        const std::string& name, std::vector<const QoreAOTSymbolIndexRecord*>& matches) {
    std::string key = qo_link_strip_leading_colons(name);
    auto it = providers.find(key);
    if (it != providers.end()) {
        matches.insert(matches.end(), it->second.begin(), it->second.end());
    }
}

static std::string qo_link_callable_base_path(const std::string& path) {
    size_t pos = path.find('(');
    return pos == std::string::npos ? path : path.substr(0, pos);
}

static bool qo_link_path_is_bare_name(const std::string& path) {
    std::string stripped = qo_link_strip_leading_colons(path);
    return !stripped.empty()
        && stripped.find("::") == std::string::npos
        && stripped.find('(') == std::string::npos;
}

static size_t qo_link_path_namespace_depth(const std::string& path) {
    std::string stripped = qo_link_strip_leading_colons(qo_link_callable_base_path(path));
    size_t depth = 0;
    size_t pos = 0;
    while ((pos = stripped.find("::", pos)) != std::string::npos) {
        ++depth;
        pos += 2;
    }
    return depth;
}

static void find_suffix_qo_providers(
        const QOLinkProviderIndex& providers,
        const std::string& name, bool callable, std::vector<const QoreAOTSymbolIndexRecord*>& matches) {
    std::string key = qo_link_strip_leading_colons(name);
    const QOLinkProviderMap& suffix_providers = callable ? providers.callable_suffix : providers.raw_suffix;
    auto it = suffix_providers.find(key);
    if (it != suffix_providers.end()) {
        matches.insert(matches.end(), it->second.begin(), it->second.end());
    }
}

static bool qo_link_call_relocation_is_callable(const QoreAOTCallRelocationRecord& rec) {
    return rec.target_kind == QoreAOTCallRelocationTargetKind::FUNCTION
        || rec.target_kind == QoreAOTCallRelocationTargetKind::METHOD
        || rec.target_kind == QoreAOTCallRelocationTargetKind::STATIC_METHOD
        || rec.target_kind == QoreAOTCallRelocationTargetKind::CONSTRUCTOR;
}

static bool qo_link_provider_matches_hashes(const QoreAOTSymbolIndexRecord& rec,
        const QoreAOTSymbolIndexRecord& provider) {
    return (rec.signature_hash.empty() || rec.signature_hash == provider.signature_hash)
        && (rec.declaration_hash.empty() || rec.declaration_hash == provider.declaration_hash)
        && (rec.value_hash.empty() || rec.value_hash == provider.value_hash)
        && (rec.body_contract_hash.empty()
            || rec.body_contract_hash == provider.body_contract_hash);
}

static bool qo_link_call_provider_matches_hashes(const QoreAOTCallRelocationRecord& rec,
        const QoreAOTSymbolIndexRecord& provider) {
    return (rec.signature_hash.empty() || rec.signature_hash == provider.signature_hash)
        && (rec.declaration_hash.empty() || rec.declaration_hash == provider.declaration_hash);
}

static std::vector<const QoreAOTSymbolIndexRecord*> dedupe_qo_provider_candidates(
        const QoreAOTSymbolIndexRecord& rec,
        const std::vector<const QoreAOTSymbolIndexRecord*>& candidates) {
    std::vector<const QoreAOTSymbolIndexRecord*> out;
    std::map<std::string, size_t> by_source;
    for (const QoreAOTSymbolIndexRecord* candidate : candidates) {
        std::string key = candidate->source_file;
        auto [it, inserted] = by_source.emplace(key, out.size());
        if (inserted) {
            out.push_back(candidate);
            continue;
        }
        const QoreAOTSymbolIndexRecord* current = out[it->second];
        if (!qo_link_provider_matches_hashes(rec, *current)
                && qo_link_provider_matches_hashes(rec, *candidate)) {
            out[it->second] = candidate;
        }
    }
    return out;
}

static bool qo_link_filter_provider_source(const QoreAOTSymbolIndexRecord& rec,
        std::vector<const QoreAOTSymbolIndexRecord*>& candidates, std::string& error) {
    if (rec.provider_source_file.empty() || rec.provider_source_file.front() == '<') {
        return true;
    }

    std::vector<const QoreAOTSymbolIndexRecord*> filtered;
    filtered.reserve(candidates.size());
    for (size_t i = 0; i < candidates.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link provider-source filtering", error)) {
            return false;
        }
        const QoreAOTSymbolIndexRecord* candidate = candidates[i];
        if (candidate->source_file == rec.provider_source_file
                || candidate->provider_source_file == rec.provider_source_file) {
            filtered.push_back(candidate);
        }
    }
    candidates.swap(filtered);
    return true;
}

static void qo_link_prefer_shallowest_provider_for_bare_import(const QoreAOTSymbolIndexRecord& rec,
        std::vector<const QoreAOTSymbolIndexRecord*>& candidates) {
    if (!qo_link_path_is_bare_name(rec.qore_path) || is_deferred_callable_qo_import(rec) || candidates.size() <= 1) {
        return;
    }

    size_t best_depth = std::numeric_limits<size_t>::max();
    for (const QoreAOTSymbolIndexRecord* candidate : candidates) {
        best_depth = std::min(best_depth, qo_link_path_namespace_depth(candidate->qore_path));
    }

    std::vector<const QoreAOTSymbolIndexRecord*> filtered;
    for (const QoreAOTSymbolIndexRecord* candidate : candidates) {
        if (qo_link_path_namespace_depth(candidate->qore_path) == best_depth) {
            filtered.push_back(candidate);
        }
    }
    candidates.swap(filtered);
}

static std::vector<const QoreAOTSymbolIndexRecord*> dedupe_qo_call_provider_candidates(
        const QoreAOTCallRelocationRecord& rec,
        const std::vector<const QoreAOTSymbolIndexRecord*>& candidates) {
    std::vector<const QoreAOTSymbolIndexRecord*> out;
    std::map<std::string, size_t> by_source;
    for (const QoreAOTSymbolIndexRecord* candidate : candidates) {
        std::string key = candidate->source_file;
        auto [it, inserted] = by_source.emplace(key, out.size());
        if (inserted) {
            out.push_back(candidate);
            continue;
        }
        const QoreAOTSymbolIndexRecord* current = out[it->second];
        if (!qo_link_call_provider_matches_hashes(rec, *current)
                && qo_link_call_provider_matches_hashes(rec, *candidate)) {
            out[it->second] = candidate;
        }
    }
    return out;
}

static const char* qo_link_call_path_scope(const std::string& path) {
    if (path.empty()) {
        return "unknown";
    }
    if (string_has_prefix(path, "Qore::")) {
        return "qore_runtime";
    }
    if (string_has_prefix(path, "Qorus::") || string_has_prefix(path, "OMQ::")) {
        return "local";
    }
    if (path.find("::") == std::string::npos) {
        return "global";
    }
    return "external_namespace";
}

static const char* qo_link_unresolved_call_reason(const QOLinkCallRelocation& reloc) {
    if (reloc.path_scope == "qore_runtime") {
        return "qore_runtime_provider";
    }
    if (reloc.dependency_class == "module_api") {
        return "external_module_api";
    }
    if (reloc.dependency_class == "module_runtime") {
        return "external_module_runtime";
    }
    if (reloc.dependency_class == "native_body") {
        return "external_native_body";
    }
    if (reloc.dependency_class == "dynamic") {
        return "dynamic_dispatch";
    }
    if (reloc.path_scope == "external_namespace") {
        return "external_namespace_provider";
    }
    if (reloc.path_scope == "global") {
        return "external_global_provider";
    }
    if (reloc.path_scope == "local") {
        return "local_provider_not_in_aggregate";
    }
    return "provider_not_found";
}

static bool validate_qo_link_inputs(const std::vector<QOLinkInputInfo>& inputs,
        QOLinkPlan& plan, std::string& error) {
    QOLinkProviderIndex providers;
    std::map<std::string, QoreAOTDependencyClass> import_classes;
    std::set<std::string> provided_seen;
    std::set<std::string> native_seen;
    std::set<std::string> dep_seen;
    std::set<std::string> prepend_seen;
    std::set<std::string> append_seen;
    std::set<std::string> module_cmd_seen;

    for (size_t i = 0; i < inputs.size(); ++i) {
        if (i && !(i % 100) && qcc_check_cancel("AOT qo-link provider collection")) {
            error = "operation cancelled during AOT qo-link provider collection";
            return false;
        }
        const QOLinkInputInfo& input = inputs[i];
        for (size_t j = 0; j < input.index.imported.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link import-class collection", error)) {
                return false;
            }
            const QoreAOTSymbolIndexRecord& rec = input.index.imported[j];
            if (!rec.qore_path.empty() && rec.dependency_class != QoreAOTDependencyClass::UNKNOWN) {
                auto [it, inserted] = import_classes.emplace(rec.qore_path, rec.dependency_class);
                if (!inserted && it->second == QoreAOTDependencyClass::UNKNOWN) {
                    it->second = rec.dependency_class;
                }
            }
        }
        for (size_t j = 0; j < input.index.defined.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link provider collection", error)) {
                return false;
            }
            const QoreAOTSymbolIndexRecord& rec = input.index.defined[j];
            if (is_owned_qore_provider(rec)) {
                qo_link_index_provider(providers, &rec);
                add_unique_string(plan.provided_qore_symbols, provided_seen, rec.qore_path);
            }
        }
        for (size_t j = 0; j < input.native_symbols.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link native symbol plan", error)) {
                return false;
            }
            add_unique_string(plan.native_symbols, native_seen, input.native_symbols[j]);
        }
        for (size_t j = 0; j < input.dependencies.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link dependency plan", error)) {
                return false;
            }
            add_unique_string(plan.external_dependencies, dep_seen, input.dependencies[j]);
        }
        for (size_t j = 0; j < input.module_path_prepend.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link module path plan", error)) {
                return false;
            }
            add_unique_string(plan.module_path_prepend, prepend_seen, input.module_path_prepend[j]);
        }
        for (size_t j = 0; j < input.module_path_append.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link module path plan", error)) {
                return false;
            }
            add_unique_string(plan.module_path_append, append_seen, input.module_path_append[j]);
        }
        for (size_t j = 0; j < input.module_commands.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link module command plan", error)) {
                return false;
            }
            const AOTModuleCommand& cmd = input.module_commands[j];
            std::string key = cmd.module + "\n" + cmd.command;
            if (module_cmd_seen.insert(key).second) {
                plan.module_commands.push_back(cmd);
            }
        }
    }

    for (size_t i = 0; i < inputs.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link import validation", error)) {
            return false;
        }
        const QOLinkInputInfo& input = inputs[i];
        for (size_t j = 0; j < input.index.imported.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link import validation", error)) {
                return false;
            }
            const QoreAOTSymbolIndexRecord& rec = input.index.imported[j];
            if (rec.qore_path.empty()) {
                continue;
            }
            QoreAOTDependencyClass dep_class = rec.dependency_class;
            if (dep_class == QoreAOTDependencyClass::MODULE_API
                    || dep_class == QoreAOTDependencyClass::MODULE_RUNTIME
                    || dep_class == QoreAOTDependencyClass::DYNAMIC) {
                continue;
            }
            bool optional_import = is_optional_qo_import(rec);

            QOLinkIssue issue;
            issue.consumer = input.path;
            issue.path = rec.qore_path;
            issue.dependency_class = qoreAOTDependencyClassName(dep_class);
            if (dep_class == QoreAOTDependencyClass::QORE_API
                    && rec.provider_source_file == "<builtin>") {
                issue.providers.push_back(rec.provider_source_file);
                plan.resolved_imports.push_back(std::move(issue));
                continue;
            }
            auto provider_it = providers.exact.find(rec.qore_path);
            std::vector<const QoreAOTSymbolIndexRecord*> deferred_callable_candidates;
            std::vector<const QoreAOTSymbolIndexRecord*> suffix_candidates;
            const std::vector<const QoreAOTSymbolIndexRecord*>* candidates_ptr =
                provider_it == providers.exact.end() ? nullptr : &provider_it->second;
            if (!candidates_ptr && is_deferred_callable_qo_import(rec)) {
                find_deferred_callable_qo_providers(providers.callable_base_exact, rec.qore_path,
                    deferred_callable_candidates);
                if (!deferred_callable_candidates.empty()) {
                    candidates_ptr = &deferred_callable_candidates;
                }
            }
            if (!candidates_ptr) {
                find_suffix_qo_providers(providers, rec.qore_path, is_deferred_callable_qo_import(rec),
                    suffix_candidates);
                if (!suffix_candidates.empty()) {
                    candidates_ptr = &suffix_candidates;
                }
            }
            if (!candidates_ptr) {
                if (!optional_import) {
                    plan.unresolved_imports.push_back(std::move(issue));
                }
                continue;
            }

            std::vector<const QoreAOTSymbolIndexRecord*> candidates =
                dedupe_qo_provider_candidates(rec, *candidates_ptr);
            if (!qo_link_filter_provider_source(rec, candidates, error)) {
                return false;
            }
            qo_link_prefer_shallowest_provider_for_bare_import(rec, candidates);
            if (candidates.empty()) {
                if (!optional_import) {
                    plan.unresolved_imports.push_back(std::move(issue));
                }
                continue;
            }
            for (size_t k = 0; k < candidates.size(); ++k) {
                if (!qo_link_check_cancel(k, "AOT qo-link provider validation", error)) {
                    return false;
                }
                issue.providers.push_back(candidates[k]->source_file);
            }
            if (candidates.size() > 1) {
                if (!optional_import) {
                    plan.ambiguous_imports.push_back(std::move(issue));
                }
                continue;
            }

            const QoreAOTSymbolIndexRecord* provider = candidates.front();
            bool mismatch = false;
            if (!rec.signature_hash.empty() && rec.signature_hash != provider->signature_hash) {
                issue.expected = "signature=" + rec.signature_hash
                    + " actual=" + provider->signature_hash;
                mismatch = true;
            } else if (!rec.declaration_hash.empty() && rec.declaration_hash != provider->declaration_hash) {
                issue.expected = "declaration=" + rec.declaration_hash
                    + " actual=" + provider->declaration_hash;
                mismatch = true;
            } else if (!rec.value_hash.empty() && rec.value_hash != provider->value_hash) {
                issue.expected = "value=" + rec.value_hash + " actual=" + provider->value_hash;
                mismatch = true;
            } else if (!rec.body_contract_hash.empty()
                    && rec.body_contract_hash
                        != provider->body_contract_hash) {
                issue.expected = "body_contract="
                    + rec.body_contract_hash + " actual="
                    + provider->body_contract_hash;
                mismatch = true;
            }
            if (mismatch) {
                if (!optional_import) {
                    plan.hash_mismatches.push_back(std::move(issue));
                }
            } else {
                plan.resolved_imports.push_back(std::move(issue));
            }
        }

        for (size_t j = 0; j < input.call_relocations.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link call-relocation validation", error)) {
                return false;
            }
            const QoreAOTCallRelocationRecord& rec = input.call_relocations[j];
            if (rec.qore_path.empty()) {
                continue;
            }
            QOLinkCallRelocation reloc;
            reloc.consumer = input.path;
            reloc.function_name = rec.function_name;
            reloc.expr_slot = rec.expr_slot;
            reloc.target_kind = qoreAOTCallRelocationTargetKindName(rec.target_kind);
            reloc.path = rec.qore_path;
            reloc.path_scope = qo_link_call_path_scope(rec.qore_path);
            auto import_it = import_classes.find(rec.qore_path);
            if (import_it != import_classes.end()) {
                reloc.dependency_class = qoreAOTDependencyClassName(import_it->second);
            }
            reloc.fallback_descriptor = rec.fallback_descriptor;
            auto provider_it = providers.exact.find(rec.qore_path);
            std::vector<const QoreAOTSymbolIndexRecord*> suffix_candidates;
            const std::vector<const QoreAOTSymbolIndexRecord*>* candidates_ptr =
                provider_it == providers.exact.end() ? nullptr : &provider_it->second;
            if (!candidates_ptr) {
                find_suffix_qo_providers(providers, rec.qore_path, qo_link_call_relocation_is_callable(rec),
                    suffix_candidates);
                if (!suffix_candidates.empty()) {
                    candidates_ptr = &suffix_candidates;
                }
            }
            if (!candidates_ptr) {
                reloc.resolution = "unresolved";
                reloc.reason = qo_link_unresolved_call_reason(reloc);
                plan.unresolved_call_relocations.push_back(std::move(reloc));
                continue;
            }

            std::vector<const QoreAOTSymbolIndexRecord*> candidates =
                dedupe_qo_call_provider_candidates(rec, *candidates_ptr);
            for (size_t k = 0; k < candidates.size(); ++k) {
                if (!qo_link_check_cancel(k, "AOT qo-link call-relocation provider validation", error)) {
                    return false;
                }
                reloc.providers.push_back(candidates[k]->source_file);
            }
            if (candidates.size() > 1) {
                reloc.resolution = "ambiguous";
                reloc.reason = "ambiguous_provider";
                plan.ambiguous_call_relocations.push_back(std::move(reloc));
                continue;
            }

            const QoreAOTSymbolIndexRecord* provider = candidates.front();
            reloc.resolution = "resolved";
            reloc.reason = "resolved";
            reloc.dependency_class = qoreAOTDependencyClassName(provider->dependency_class);
            reloc.provider_kind = qoreAOTSymbolKindName(provider->kind);
            reloc.provider_source = provider->source_file;
            bool mismatch = false;
            if (!rec.signature_hash.empty() && rec.signature_hash != provider->signature_hash) {
                reloc.expected = "signature=" + rec.signature_hash
                    + " actual=" + provider->signature_hash;
                reloc.resolution = "hash_mismatch";
                reloc.reason = "signature_hash_mismatch";
                mismatch = true;
            } else if (!rec.declaration_hash.empty() && rec.declaration_hash != provider->declaration_hash) {
                reloc.expected = "declaration=" + rec.declaration_hash
                    + " actual=" + provider->declaration_hash;
                reloc.resolution = "hash_mismatch";
                reloc.reason = "declaration_hash_mismatch";
                mismatch = true;
            }
            reloc.native_symbol = provider->native_symbol;
            if (mismatch) {
                plan.call_relocation_hash_mismatches.push_back(std::move(reloc));
            } else {
                plan.resolved_call_relocations.push_back(std::move(reloc));
            }
        }
    }

    std::sort(plan.provided_qore_symbols.begin(), plan.provided_qore_symbols.end());
    std::sort(plan.native_symbols.begin(), plan.native_symbols.end());
    std::sort(plan.external_dependencies.begin(), plan.external_dependencies.end());
    std::sort(plan.module_path_prepend.begin(), plan.module_path_prepend.end());
    std::sort(plan.module_path_append.begin(), plan.module_path_append.end());
    std::sort(plan.module_commands.begin(), plan.module_commands.end(),
        [](const AOTModuleCommand& a, const AOTModuleCommand& b) {
            return std::tie(a.module, a.command) < std::tie(b.module, b.command);
        });
    auto call_reloc_less = [](const QOLinkCallRelocation& a, const QOLinkCallRelocation& b) {
        return std::tie(a.consumer, a.function_name, a.expr_slot, a.target_kind, a.path)
            < std::tie(b.consumer, b.function_name, b.expr_slot, b.target_kind, b.path);
    };
    std::sort(plan.resolved_call_relocations.begin(), plan.resolved_call_relocations.end(), call_reloc_less);
    std::sort(plan.unresolved_call_relocations.begin(), plan.unresolved_call_relocations.end(), call_reloc_less);
    std::sort(plan.ambiguous_call_relocations.begin(), plan.ambiguous_call_relocations.end(), call_reloc_less);
    std::sort(plan.call_relocation_hash_mismatches.begin(), plan.call_relocation_hash_mismatches.end(),
        call_reloc_less);
    return true;
}

static void json_file_string(FILE* f, const std::string& value) {
    fputc('"', f);
    for (unsigned char c : value) {
        switch (c) {
            case '"': fputs("\\\"", f); break;
            case '\\': fputs("\\\\", f); break;
            case '\b': fputs("\\b", f); break;
            case '\f': fputs("\\f", f); break;
            case '\n': fputs("\\n", f); break;
            case '\r': fputs("\\r", f); break;
            case '\t': fputs("\\t", f); break;
            default:
                if (c < 0x20) {
                    fprintf(f, "\\u%04x", c);
                } else {
                    fputc(c, f);
                }
                break;
        }
    }
    fputc('"', f);
}

static bool json_file_string_array(FILE* f, const char* key,
        const std::vector<std::string>& values, std::string& error, const char* comma = ",") {
    fprintf(f, "  \"%s\": [", key);
    for (size_t i = 0; i < values.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link map string array write", error)) {
            return false;
        }
        if (i) {
            fputc(',', f);
        }
        fputc('\n', f);
        fputs("    ", f);
        json_file_string(f, values[i]);
    }
    if (!values.empty()) {
        fputc('\n', f);
        fputs("  ", f);
    }
    fprintf(f, "]%s\n", comma);
    return true;
}

static bool json_file_issue_array(FILE* f, const char* key,
        const std::vector<QOLinkIssue>& issues, std::string& error, const char* comma = ",") {
    fprintf(f, "  \"%s\": [", key);
    for (size_t i = 0; i < issues.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link map issue write", error)) {
            return false;
        }
        const QOLinkIssue& issue = issues[i];
        if (i) {
            fputc(',', f);
        }
        fputs("\n    {\"consumer\": ", f);
        json_file_string(f, issue.consumer);
        fputs(", \"path\": ", f);
        json_file_string(f, issue.path);
        fputs(", \"dependency_class\": ", f);
        json_file_string(f, issue.dependency_class);
        fputs(", \"expected\": ", f);
        json_file_string(f, issue.expected);
        fputs(", \"providers\": [", f);
        for (size_t j = 0; j < issue.providers.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link map issue provider write", error)) {
                return false;
            }
            if (j) {
                fputs(", ", f);
            }
            json_file_string(f, issue.providers[j]);
        }
        fputs("]}", f);
    }
    if (!issues.empty()) {
        fputc('\n', f);
        fputs("  ", f);
    }
    fprintf(f, "]%s\n", comma);
    return true;
}

static bool json_file_call_relocation_array(FILE* f, const char* key,
        const std::vector<QOLinkCallRelocation>& relocs, std::string& error,
        const char* comma = ",") {
    fprintf(f, "  \"%s\": [", key);
    for (size_t i = 0; i < relocs.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link map call-relocation write", error)) {
            return false;
        }
        const QOLinkCallRelocation& reloc = relocs[i];
        if (i) {
            fputc(',', f);
        }
        fputs("\n    {\"consumer\": ", f);
        json_file_string(f, reloc.consumer);
        fputs(", \"function\": ", f);
        json_file_string(f, reloc.function_name);
        fprintf(f, ", \"expr_slot\": %u", reloc.expr_slot);
        fputs(", \"target_kind\": ", f);
        json_file_string(f, reloc.target_kind);
        fputs(", \"path\": ", f);
        json_file_string(f, reloc.path);
        fputs(", \"path_scope\": ", f);
        json_file_string(f, reloc.path_scope);
        fputs(", \"dependency_class\": ", f);
        json_file_string(f, reloc.dependency_class);
        fputs(", \"resolution\": ", f);
        json_file_string(f, reloc.resolution);
        fputs(", \"reason\": ", f);
        json_file_string(f, reloc.reason);
        fputs(", \"expected\": ", f);
        json_file_string(f, reloc.expected);
        fputs(", \"provider_kind\": ", f);
        json_file_string(f, reloc.provider_kind);
        fputs(", \"provider_source\": ", f);
        json_file_string(f, reloc.provider_source);
        fputs(", \"native_symbol\": ", f);
        json_file_string(f, reloc.native_symbol);
        fputs(", \"fallback_descriptor\": ", f);
        json_file_string(f, reloc.fallback_descriptor);
        fputs(", \"providers\": [", f);
        for (size_t j = 0; j < reloc.providers.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link map call-relocation provider write", error)) {
                return false;
            }
            if (j) {
                fputs(", ", f);
            }
            json_file_string(f, reloc.providers[j]);
        }
        fputs("]}", f);
    }
    if (!relocs.empty()) {
        fputc('\n', f);
        fputs("  ", f);
    }
    fprintf(f, "]%s\n", comma);
    return true;
}

static bool add_qo_link_call_relocation_reason_counts(
        std::map<std::string, size_t>& reasons,
        const std::vector<QOLinkCallRelocation>& relocs,
        const char* operation,
        std::string& error) {
    for (size_t i = 0; i < relocs.size(); ++i) {
        if (!qo_link_check_cancel(i, operation, error)) {
            return false;
        }
        const std::string& reason = relocs[i].reason.empty() ? relocs[i].resolution : relocs[i].reason;
        ++reasons[reason.empty() ? "unknown" : reason];
    }
    return true;
}

static bool json_file_call_relocation_summary(FILE* f, const QOLinkPlan& plan,
        std::string& error, const char* comma = ",") {
    std::map<std::string, size_t> reasons;
    if (!add_qo_link_call_relocation_reason_counts(reasons, plan.resolved_call_relocations,
            "AOT qo-link map call-relocation summary write", error)
            || !add_qo_link_call_relocation_reason_counts(reasons, plan.unresolved_call_relocations,
                "AOT qo-link map call-relocation summary write", error)
            || !add_qo_link_call_relocation_reason_counts(reasons, plan.ambiguous_call_relocations,
                "AOT qo-link map call-relocation summary write", error)
            || !add_qo_link_call_relocation_reason_counts(reasons, plan.call_relocation_hash_mismatches,
                "AOT qo-link map call-relocation summary write", error)) {
        return false;
    }

    const size_t resolved = plan.resolved_call_relocations.size();
    const size_t unresolved = plan.unresolved_call_relocations.size();
    const size_t ambiguous = plan.ambiguous_call_relocations.size();
    const size_t hash_mismatches = plan.call_relocation_hash_mismatches.size();
    const size_t total = resolved + unresolved + ambiguous + hash_mismatches;
    fprintf(f,
        "  \"call_relocation_summary\": {\n"
        "    \"total\": %llu,\n"
        "    \"resolved\": %llu,\n"
        "    \"unresolved\": %llu,\n"
        "    \"ambiguous\": %llu,\n"
        "    \"hash_mismatches\": %llu,\n"
        "    \"reasons\": [",
        static_cast<unsigned long long>(total),
        static_cast<unsigned long long>(resolved),
        static_cast<unsigned long long>(unresolved),
        static_cast<unsigned long long>(ambiguous),
        static_cast<unsigned long long>(hash_mismatches));
    size_t i = 0;
    for (const auto& entry : reasons) {
        if (!qo_link_check_cancel(i, "AOT qo-link map call-relocation reason write", error)) {
            return false;
        }
        if (i) {
            fputc(',', f);
        }
        fputs("\n      {\"reason\": ", f);
        json_file_string(f, entry.first);
        fprintf(f, ", \"count\": %llu}", static_cast<unsigned long long>(entry.second));
        ++i;
    }
    if (!reasons.empty()) {
        fputc('\n', f);
        fputs("    ", f);
    }
    fprintf(f, "]\n  }%s\n", comma);
    return true;
}

static bool write_qo_link_map(const std::string& path, const std::string& output,
        const std::string& aggregate_symbol, const std::vector<QOLinkInputInfo>& inputs,
        const QOLinkPlan& plan, std::string& error) {
    FILE* f = fopen(path.c_str(), "w");
    if (!f) {
        error = "cannot open qo link map '" + path + "': " + strerror(errno);
        return false;
    }

    fprintf(f, "{\n");
    fputs("  \"format\": 1,\n", f);
    fputs("  \"output\": ", f);
    json_file_string(f, output);
    fputs(",\n  \"aggregate_symbol\": ", f);
    json_file_string(f, aggregate_symbol);
    fprintf(f, ",\n  \"allow_unresolved_imports\": %s",
        allow_unresolved_qo_imports ? "true" : "false");
    fputs(",\n  \"inputs\": [", f);
    for (size_t i = 0; i < inputs.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link map input write", error)) {
            fclose(f);
            return false;
        }
        const QOLinkInputInfo& input = inputs[i];
        if (i) {
            fputc(',', f);
        }
        fputs("\n    {\"path\": ", f);
        json_file_string(f, input.path);
        fputs(", \"object_hash\": ", f);
        json_file_string(f, input.object_hash);
        fprintf(f, ", \"object_size\": %llu, \"register_symbol\": ",
            static_cast<unsigned long long>(input.object_size));
        json_file_string(f, input.register_symbol);
        fputs(", \"source_text\": [", f);
        for (size_t j = 0; j < input.source_text.size(); ++j) {
            if (!qo_link_check_cancel(j, "AOT qo-link map source-text write", error)) {
                fclose(f);
                return false;
            }
            if (j) {
                fputs(", ", f);
            }
            json_file_string(f, input.source_text[j]);
        }
        fputs("]}", f);
    }
    if (!inputs.empty()) {
        fputc('\n', f);
        fputs("  ", f);
    }
    fputs("],\n", f);

    std::vector<std::string> register_symbols;
    register_symbols.reserve(inputs.size());
    for (size_t i = 0; i < inputs.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link map register-symbol collection", error)) {
            fclose(f);
            return false;
        }
        register_symbols.push_back(inputs[i].register_symbol);
    }
    if (!json_file_string_array(f, "register_symbols", register_symbols, error)
            || !json_file_string_array(f, "provided_qore_symbols", plan.provided_qore_symbols, error)
            || !json_file_string_array(f, "native_symbols", plan.native_symbols, error)
            || !json_file_string_array(f, "external_dependencies", plan.external_dependencies, error)
            || !json_file_string_array(f, "module_path_prepend", plan.module_path_prepend, error)
            || !json_file_string_array(f, "module_path_append", plan.module_path_append, error)) {
        fclose(f);
        return false;
    }

    fputs("  \"module_commands\": [", f);
    for (size_t i = 0; i < plan.module_commands.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT qo-link map module-command write", error)) {
            fclose(f);
            return false;
        }
        const AOTModuleCommand& cmd = plan.module_commands[i];
        if (i) {
            fputc(',', f);
        }
        fputs("\n    {\"module\": ", f);
        json_file_string(f, cmd.module);
        fputs(", \"command\": ", f);
        json_file_string(f, cmd.command);
        fputs("}", f);
    }
    if (!plan.module_commands.empty()) {
        fputc('\n', f);
        fputs("  ", f);
    }
    fputs("],\n", f);

    if (!json_file_issue_array(f, "resolved_imports", plan.resolved_imports, error)
            || !json_file_issue_array(f, "unresolved_imports", plan.unresolved_imports, error)
            || !json_file_issue_array(f, "ambiguous_imports", plan.ambiguous_imports, error)
            || !json_file_issue_array(f, "hash_mismatches", plan.hash_mismatches, error)
            || !json_file_call_relocation_summary(f, plan, error)
            || !json_file_call_relocation_array(f, "resolved_call_relocations",
                plan.resolved_call_relocations, error)
            || !json_file_call_relocation_array(f, "unresolved_call_relocations",
                plan.unresolved_call_relocations, error)
            || !json_file_call_relocation_array(f, "ambiguous_call_relocations",
                plan.ambiguous_call_relocations, error)
            || !json_file_call_relocation_array(f, "call_relocation_hash_mismatches",
                plan.call_relocation_hash_mismatches, error, "")) {
        fclose(f);
        return false;
    }
    fputs("}\n", f);

    if (fclose(f) != 0) {
        error = "cannot close qo link map '" + path + "': " + strerror(errno);
        return false;
    }
    return true;
}

static void print_qo_link_issues(const char* label, const std::vector<QOLinkIssue>& issues) {
    for (size_t i = 0; i < issues.size(); ++i) {
        if (i && !(i % 100) && qcc_check_cancel("AOT qo-link issue reporting")) {
            fprintf(stderr, "error: operation cancelled during AOT qo-link issue reporting\n");
            return;
        }
        const QOLinkIssue& issue = issues[i];
        fprintf(stderr, "error: qo-link %s: consumer='%s' symbol='%s' class='%s'",
            label, issue.consumer.c_str(), issue.path.c_str(), issue.dependency_class.c_str());
        if (!issue.expected.empty()) {
            fprintf(stderr, " %s", issue.expected.c_str());
        }
        if (!issue.providers.empty()) {
            fprintf(stderr, " providers=");
            for (size_t j = 0; j < issue.providers.size(); ++j) {
                if (j && !(j % 100) && qcc_check_cancel("AOT qo-link issue provider reporting")) {
                    fprintf(stderr, "\nerror: operation cancelled during AOT qo-link issue provider reporting\n");
                    return;
                }
                fprintf(stderr, "%s%s", j ? "," : "", issue.providers[j].c_str());
            }
        }
        fputc('\n', stderr);
    }
}

static void print_qo_link_call_relocation_issues(const char* label,
        const std::vector<QOLinkCallRelocation>& relocs) {
    for (size_t i = 0; i < relocs.size(); ++i) {
        if (i && !(i % 100) && qcc_check_cancel("AOT qo-link call-relocation issue reporting")) {
            fprintf(stderr, "error: operation cancelled during AOT qo-link call-relocation issue reporting\n");
            return;
        }
        const QOLinkCallRelocation& reloc = relocs[i];
        fprintf(stderr, "error: qo-link %s call relocation: consumer='%s' function='%s' slot=%u "
            "target='%s' symbol='%s' reason='%s'",
            label, reloc.consumer.c_str(), reloc.function_name.c_str(), reloc.expr_slot,
            reloc.target_kind.c_str(), reloc.path.c_str(),
            reloc.reason.empty() ? reloc.resolution.c_str() : reloc.reason.c_str());
        if (!reloc.expected.empty()) {
            fprintf(stderr, " %s", reloc.expected.c_str());
        }
        if (!reloc.providers.empty()) {
            fprintf(stderr, " providers=");
            for (size_t j = 0; j < reloc.providers.size(); ++j) {
                if (j && !(j % 100)
                        && qcc_check_cancel("AOT qo-link call-relocation provider reporting")) {
                    fprintf(stderr,
                        "\nerror: operation cancelled during AOT qo-link call-relocation provider reporting\n");
                    return;
                }
                fprintf(stderr, "%s%s", j ? "," : "", reloc.providers[j].c_str());
            }
        }
        fputc('\n', stderr);
    }
}

static void dump_object_sections(const llvm::object::ObjectFile& obj) {
    printf("  object sections:\n");
    for (const llvm::object::SectionRef& sec : obj.sections()) {
        auto name_or = sec.getName();
        std::string name;
        if (name_or) {
            name = name_or->str();
        } else {
            llvm::consumeError(name_or.takeError());
        }
        printf("    0x%016llx %10llu %s\n",
            static_cast<unsigned long long>(sec.getAddress()),
            static_cast<unsigned long long>(sec.getSize()),
            name.c_str());
    }
}

static void dump_object_symbols(const llvm::object::ObjectFile& obj, bool all_symbols) {
    std::vector<AOTDumpSymbolRow> rows = collect_symbol_rows(obj);
    size_t qore_count = 0;
    for (const AOTDumpSymbolRow& row : rows) {
        if (row.qore_relevant) {
            ++qore_count;
        }
    }

    printf("  symbols: %zu total, %zu qore/aot%s\n", rows.size(), qore_count,
        all_symbols ? "" : " (important symbols shown)");
    for (const AOTDumpSymbolRow& row : rows) {
        if (!all_symbols && !row.qore_relevant) {
            continue;
        }
        printf("    %016llx %8llu %c %-18s %s\n",
            static_cast<unsigned long long>(row.value),
            static_cast<unsigned long long>(row.size),
            row.kind, row.section.c_str(), row.name.c_str());
    }
}

static void dump_object_symbol_summary(const llvm::object::ObjectFile& obj) {
    std::vector<AOTDumpSymbolRow> rows = collect_symbol_rows(obj);
    size_t qore_count = 0;
    for (const AOTDumpSymbolRow& row : rows) {
        if (row.qore_relevant) {
            ++qore_count;
        }
    }

    printf("  symbols: %zu total, %zu qore/aot (use --dump-symbols to list)\n",
        rows.size(), qore_count);
}

static void inspect_object_file(const char* path,
        std::vector<AOTDumpMetadataBlob>& blobs, std::set<std::string>& seen) {
    auto binary_or = llvm::object::createBinary(path);
    if (!binary_or) {
        if (dump_symbols || dump_sections) {
            std::string msg = llvm::toString(binary_or.takeError());
            printf("  object: not recognized: %s\n", msg.c_str());
        } else {
            llvm::consumeError(binary_or.takeError());
        }
        return;
    }

    llvm::object::Binary* binary = binary_or->getBinary();
    auto* obj = llvm::dyn_cast<llvm::object::ObjectFile>(binary);
    if (!obj) {
        printf("  object: %s\n", binary->getFileName().str().c_str());
        printf("  object symbols/sections: unsupported container type\n");
        return;
    }

    printf("  object: %s\n", obj->getFileFormatName().str().c_str());
    extract_aot_metadata_from_object(*obj, blobs, seen);
    if (dump_sections) {
        dump_object_sections(*obj);
    }
    if (dump_symbols) {
        dump_object_symbols(*obj, true);
    } else if (dump_info) {
        dump_object_symbol_summary(*obj);
    }
}

static void collect_object_metadata_quiet(const char* path,
        std::vector<AOTDumpMetadataBlob>& blobs, std::set<std::string>& seen) {
    auto binary_or = llvm::object::createBinary(path);
    if (!binary_or) {
        llvm::consumeError(binary_or.takeError());
        return;
    }

    llvm::object::Binary* binary = binary_or->getBinary();
    auto* obj = llvm::dyn_cast<llvm::object::ObjectFile>(binary);
    if (!obj) {
        return;
    }

    extract_aot_metadata_from_object(*obj, blobs, seen);
}

static std::string hex64_string(uint64_t value) {
    char buf[17];
    snprintf(buf, sizeof(buf), "%016llx", static_cast<unsigned long long>(value));
    return buf;
}

static bool json_output_cancelled = false;

static void json_print_string(const std::string& value) {
    putchar('"');
    size_t i = 0;
    for (unsigned char c : value) {
        if (i && !(i % 100) && qcc_check_cancel("AOT symbol-index JSON string dump")) {
            fprintf(stderr, "error: operation cancelled during AOT symbol-index JSON string dump\n");
            json_output_cancelled = true;
            return;
        }
        ++i;
        switch (c) {
            case '"':
                printf("\\\"");
                break;
            case '\\':
                printf("\\\\");
                break;
            case '\b':
                printf("\\b");
                break;
            case '\f':
                printf("\\f");
                break;
            case '\n':
                printf("\\n");
                break;
            case '\r':
                printf("\\r");
                break;
            case '\t':
                printf("\\t");
                break;
            default:
                if (c < 0x20) {
                    printf("\\u%04x", static_cast<unsigned>(c));
                } else {
                    putchar(c);
                }
                break;
        }
    }
    putchar('"');
}

static void json_print_key(const char* key, unsigned indent) {
    printf("%*s", static_cast<int>(indent), "");
    json_print_string(key ? key : "");
    printf(": ");
}

static void json_print_string_field(const char* key, const std::string& value,
        unsigned indent, bool comma = true) {
    json_print_key(key, indent);
    json_print_string(value);
    printf("%s\n", comma ? "," : "");
}

static void json_print_u64_field(const char* key, uint64_t value,
        unsigned indent, bool comma = true) {
    json_print_key(key, indent);
    printf("%llu%s\n", static_cast<unsigned long long>(value), comma ? "," : "");
}

static bool json_dump_check_cancel(size_t ordinal, const char* operation) {
    if (ordinal && !(ordinal % 100) && qcc_check_cancel(operation)) {
        fprintf(stderr, "error: operation cancelled during %s\n",
            operation ? operation : "AOT symbol-index JSON dump");
        return false;
    }
    return true;
}

static bool json_print_string_array(const char* key, const std::vector<std::string>& values,
        unsigned indent, bool comma = true) {
    json_print_key(key, indent);
    printf("[");
    for (size_t i = 0; i < values.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT symbol-index JSON string-array dump")) {
            return false;
        }
        if (i) {
            printf(", ");
        }
        json_print_string(values[i]);
    }
    printf("]%s\n", comma ? "," : "");
    return true;
}

static bool json_print_context_array(const char* key,
        const std::vector<std::pair<std::string, std::string>>& values,
        unsigned indent, bool comma = true) {
    json_print_key(key, indent);
    printf("[");
    for (size_t i = 0; i < values.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT symbol-index JSON context dump")) {
            return false;
        }
        if (i) {
            printf(",");
        }
        printf("\n%*s{", static_cast<int>(indent + 2), "");
        json_print_string("key");
        printf(": ");
        json_print_string(values[i].first);
        printf(", ");
        json_print_string("value");
        printf(": ");
        json_print_string(values[i].second);
        printf("}");
    }
    if (!values.empty()) {
        printf("\n%*s", static_cast<int>(indent), "");
    }
    printf("]%s\n", comma ? "," : "");
    return true;
}

static bool json_collect_context_values(const std::vector<std::pair<std::string, std::string>>& values,
        const char* key, std::vector<std::string>& out) {
    for (size_t i = 0; i < values.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT symbol-index JSON context value collection")) {
            return false;
        }
        if (values[i].first == key) {
            out.push_back(values[i].second);
        }
    }
    return true;
}

static bool json_print_symbol_record(const QoreAOTSymbolIndexRecord& rec, unsigned indent) {
    printf("%*s{", static_cast<int>(indent), "");
    json_print_string("kind");
    printf(": ");
    json_print_string(qoreAOTSymbolKindName(rec.kind));
    printf(", ");
    json_print_string("dependency_class");
    printf(": ");
    json_print_string(qoreAOTDependencyClassName(rec.dependency_class));
    printf(", ");
    json_print_string("flags");
    printf(": %u, ", rec.flags);
    json_print_string("metadata_slot");
    if (rec.metadata_slot == UINT32_MAX) {
        printf(": null");
    } else {
        printf(": %u", rec.metadata_slot);
    }
    printf(", ");
    json_print_string("qore_path");
    printf(": ");
    json_print_string(rec.qore_path);
    printf(", ");
    json_print_string("source_file");
    printf(": ");
    json_print_string(rec.source_file);
    printf(", ");
    json_print_string("visibility");
    printf(": ");
    json_print_string(rec.visibility);
    printf(", ");
    json_print_string("signature_hash");
    printf(": ");
    json_print_string(rec.signature_hash);
    printf(", ");
    json_print_string("declaration_hash");
    printf(": ");
    json_print_string(rec.declaration_hash);
    printf(", ");
    json_print_string("value_hash");
    printf(": ");
    json_print_string(rec.value_hash);
    printf(", ");
    json_print_string("body_contract_hash");
    printf(": ");
    json_print_string(rec.body_contract_hash);
    printf(", ");
    json_print_string("native_symbol");
    printf(": ");
    json_print_string(rec.native_symbol);
    printf(", ");
    json_print_string("abi_kind");
    printf(": ");
    json_print_string(rec.abi_kind);
    printf(", ");
    json_print_string("consumer_source_file");
    printf(": ");
    json_print_string(rec.consumer_source_file);
    printf(", ");
    json_print_string("provider_source_file");
    printf(": ");
    json_print_string(rec.provider_source_file);
    printf(", \"fast_entry_flags\": %u, \"fast_entry_num_params\": %u, \"fast_return_kind\": %u",
        rec.fast_entry_flags, rec.fast_entry_num_params, rec.fast_return_kind);
    printf(", \"fast_specialization_key\": ");
    json_print_string(rec.fast_specialization_key);
    auto print_bytes = [](const char* name, const std::vector<uint8_t>& values) {
        printf(", \"%s\": [", name);
        for (size_t i = 0; i < values.size(); ++i) {
            if (i && !(i % 100)
                    && qcc_check_cancel("AOT fast-entry parameter JSON dump")) {
                break;
            }
            printf("%s%u", i ? ", " : "", values[i]);
        }
        printf("]");
    };
    print_bytes("fast_param_kinds", rec.fast_param_kinds);
    print_bytes("fast_param_rejects_nothing", rec.fast_param_rejects_nothing);
    print_bytes("fast_param_noescape", rec.fast_param_noescape);
    print_bytes("fast_param_may_modify", rec.fast_param_may_modify);
    printf(", \"scalar_leaf_kind\": %u, \"scalar_leaf_opcode\": %u"
        ", \"scalar_leaf_lhs_param\": %d, \"scalar_leaf_rhs_param\": %d"
        ", \"scalar_leaf_lhs_int\": " QLLD ", \"scalar_leaf_rhs_int\": " QLLD
        ", \"scalar_leaf_lhs_float\": %.17g, \"scalar_leaf_rhs_float\": %.17g"
        ", \"scalar_leaf_true_scale\": " QLLD ", \"scalar_leaf_true_offset\": " QLLD
        ", \"scalar_leaf_false_scale\": " QLLD ", \"scalar_leaf_false_offset\": " QLLD
        ", \"object_getter_member\": ",
        rec.scalar_leaf_kind, rec.scalar_leaf_opcode,
        rec.scalar_leaf_lhs_param, rec.scalar_leaf_rhs_param,
        static_cast<long long>(rec.scalar_leaf_lhs_int),
        static_cast<long long>(rec.scalar_leaf_rhs_int),
        rec.scalar_leaf_lhs_float, rec.scalar_leaf_rhs_float,
        static_cast<long long>(rec.scalar_leaf_true_scale),
        static_cast<long long>(rec.scalar_leaf_true_offset),
        static_cast<long long>(rec.scalar_leaf_false_scale),
        static_cast<long long>(rec.scalar_leaf_false_offset));
    json_print_string(rec.object_getter_member);
    printf(", \"object_set_get_member\": ");
    json_print_string(rec.object_set_get_member);
    printf(", \"object_set_get_param\": %d",
        rec.object_set_get_param);
    printf(", \"object_compound_get_member\": ");
    json_print_string(rec.object_compound_get_member);
    printf(", \"object_compound_get_param\": %d"
        ", \"object_compound_get_op\": %u",
        rec.object_compound_get_param, rec.object_compound_get_op);
    printf(", \"string_op_kind\": %u, \"string_op_base_param\": %d"
        ", \"string_op_arg0_param\": %d, \"string_op_arg1_param\": %d",
        rec.string_op_kind, rec.string_op_base_param,
        rec.string_op_arg0_param, rec.string_op_arg1_param);
    printf(", \"collection_op_kind\": %u, \"collection_op_base_param\": %d"
        ", \"collection_op_index_param\": %d, \"collection_op_string_index_char\": %s"
        ", \"collection_op_key\": ", rec.collection_op_kind,
        rec.collection_op_base_param, rec.collection_op_index_param,
        rec.collection_op_string_index_char ? "true" : "false");
    json_print_string(rec.collection_op_key);
    printf(", \"aggregate_return_kind\": %u, \"aggregate_return_value_params\": [",
        rec.aggregate_return_kind);
    for (size_t i = 0; i < rec.aggregate_return_value_params.size(); ++i) {
        printf("%s%d", i ? ", " : "",
            rec.aggregate_return_value_params[i]);
    }
    printf("], \"aggregate_return_value_kinds\": [");
    for (size_t i = 0; i < rec.aggregate_return_value_kinds.size(); ++i) {
        printf("%s%u", i ? ", " : "",
            rec.aggregate_return_value_kinds[i]);
    }
    printf("], \"aggregate_return_value_ints\": [");
    for (size_t i = 0; i < rec.aggregate_return_value_ints.size(); ++i) {
        printf("%s" QLLD, i ? ", " : "",
            static_cast<long long>(rec.aggregate_return_value_ints[i]));
    }
    printf("], \"aggregate_return_value_floats\": [");
    for (size_t i = 0; i < rec.aggregate_return_value_floats.size(); ++i) {
        printf("%s%.17g", i ? ", " : "",
            rec.aggregate_return_value_floats[i]);
    }
    printf("], \"aggregate_return_keys\": [");
    for (size_t i = 0; i < rec.aggregate_return_keys.size(); ++i) {
        if (i) {
            printf(", ");
        }
        json_print_string(rec.aggregate_return_keys[i]);
    }
    printf("], \"aggregate_return_shape_condition_param\": %d"
        ", \"aggregate_return_shape_true_size\": %u"
        ", \"aggregate_return_shape_false_size\": %u"
        ", \"aggregate_return_value_selects\": [",
        rec.aggregate_return_shape_condition_param,
        rec.aggregate_return_shape_true_size,
        rec.aggregate_return_shape_false_size);
    for (size_t i = 0;
            i < rec.aggregate_return_value_selects.size(); ++i) {
        const auto& select = rec.aggregate_return_value_selects[i];
        printf("%s{\"value_index\": %u, \"condition_param\": %d"
            ", \"true_kind\": %u, \"true_param\": %d"
            ", \"true_int\": " QLLD ", \"true_float\": %.17g"
            ", \"false_kind\": %u, \"false_param\": %d"
            ", \"false_int\": " QLLD ", \"false_float\": %.17g}",
            i ? ", " : "", select.value_index,
            select.condition_param, select.true_value.kind,
            select.true_value.param,
            static_cast<long long>(select.true_value.int_value),
            select.true_value.float_value, select.false_value.kind,
            select.false_value.param,
            static_cast<long long>(select.false_value.int_value),
            select.false_value.float_value);
    }
    printf("], \"boxed_return_param\": %d, \"boxed_return_kind\": %u",
        rec.boxed_return_param, rec.boxed_return_kind);
    printf(", \"composed_int_source_kind\": %u, \"composed_int_base_param\": %d"
        ", \"composed_int_value_param\": %d, \"composed_int_source_scale\": " QLLD
        ", \"composed_int_value_scale\": " QLLD ", \"composed_int_offset\": " QLLD,
        rec.composed_int_source_kind, rec.composed_int_base_param,
        rec.composed_int_value_param,
        static_cast<long long>(rec.composed_int_source_scale),
        static_cast<long long>(rec.composed_int_value_scale),
        static_cast<long long>(rec.composed_int_offset));
    printf(", \"global_int_value_param\": %d, \"global_int_slot\": %d"
        ", \"global_int_value_scale\": " QLLD ", \"global_int_global_scale\": " QLLD
        ", \"global_int_offset\": " QLLD,
        rec.global_int_value_param, rec.global_int_slot,
        static_cast<long long>(rec.global_int_value_scale),
        static_cast<long long>(rec.global_int_global_scale),
        static_cast<long long>(rec.global_int_offset));
    printf(", \"int_expression_nodes\": [");
    for (size_t i = 0; i < rec.int_expression_nodes.size(); ++i) {
        const auto& node = rec.int_expression_nodes[i];
        printf("%s{\"kind\": %u, \"lhs\": %u, \"rhs\": %u, \"third\": %u, \"param\": %d"
            ", \"constant\": " QLLD ", \"key\": ", i ? ", " : "", node.kind,
            node.lhs, node.rhs, node.third, node.param,
            static_cast<long long>(node.constant));
        json_file_string(stdout, node.key);
        printf("}");
    }
    printf("]");
    printf(", \"float_expression_nodes\": [");
    for (size_t i = 0; i < rec.float_expression_nodes.size(); ++i) {
        const auto& node = rec.float_expression_nodes[i];
        printf("%s{\"kind\": %u, \"lhs\": %u, \"rhs\": %u, \"param\": %d"
            ", \"constant\": %.17g, \"key\": ", i ? ", " : "", node.kind,
            node.lhs, node.rhs, node.param, node.constant);
        json_file_string(stdout, node.key);
        printf("}");
    }
    printf("]");
    printf(", \"string_expression_nodes\": [");
    for (size_t i = 0; i < rec.string_expression_nodes.size(); ++i) {
        const auto& node = rec.string_expression_nodes[i];
        printf("%s{\"kind\": %u, \"lhs\": %u, \"rhs\": %u, \"third\": %u"
            ", \"param\": %d, \"int_constant\": " QLLD
            ", \"string_constant\": ", i ? ", " : "", node.kind,
            node.lhs, node.rhs, node.third, node.param,
            static_cast<long long>(node.int_constant));
        json_print_string(node.string_constant);
        printf("}");
    }
    printf("]");
    printf(", \"body_dependency_files\": [");
    for (size_t i = 0; i < rec.body_dependency_files.size(); ++i) {
        if (i && !(i % 100)
                && qcc_check_cancel(
                    "AOT body dependency JSON output")) {
            return false;
        }
        if (i) {
            printf(", ");
        }
        json_print_string(rec.body_dependency_files[i]);
    }
    printf("]");
    printf(", \"body_contract_dependencies\": [");
    for (size_t i = 0; i < rec.body_contract_dependencies.size(); ++i) {
        if (i && !(i % 100)
                && qcc_check_cancel(
                    "AOT body contract dependency JSON output")) {
            return false;
        }
        if (i) {
            printf(", ");
        }
        const auto& dependency = rec.body_contract_dependencies[i];
        printf("{\"qore_path\": ");
        json_print_string(dependency.qore_path);
        printf(", \"provider_source_file\": ");
        json_print_string(dependency.provider_source_file);
        printf(", \"body_contract_hash\": ");
        json_print_string(dependency.body_contract_hash);
        printf("}");
    }
    printf("]");
    printf("}");
    return true;
}

static bool json_print_symbol_array(const char* key,
        const std::vector<QoreAOTSymbolIndexRecord>& records,
        unsigned indent, bool comma = true) {
    json_print_key(key, indent);
    printf("[");
    for (size_t i = 0; i < records.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT symbol-index JSON record dump")) {
            return false;
        }
        if (i) {
            printf(",");
        }
        printf("\n");
        if (!json_print_symbol_record(records[i], indent + 2)) {
            return false;
        }
    }
    if (!records.empty()) {
        printf("\n%*s", static_cast<int>(indent), "");
    }
    printf("]%s\n", comma ? "," : "");
    return true;
}

static void json_print_call_relocation_record(const QoreAOTCallRelocationRecord& rec,
        unsigned indent) {
    printf("%*s{", static_cast<int>(indent), "");
    json_print_string("function");
    printf(": ");
    json_print_string(rec.function_name);
    printf(", ");
    json_print_string("expr_slot");
    printf(": %u, ", rec.expr_slot);
    json_print_string("target_kind");
    printf(": ");
    json_print_string(qoreAOTCallRelocationTargetKindName(rec.target_kind));
    printf(", ");
    json_print_string("strictness");
    printf(": ");
    json_print_string(rec.strictness == QoreAOTCallRelocationStrictness::REQUIRED ? "required" : "optional");
    printf(", ");
    json_print_string("qore_path");
    printf(": ");
    json_print_string(rec.qore_path);
    printf(", ");
    json_print_string("path");
    printf(": ");
    json_print_string(rec.qore_path);
    printf(", ");
    json_print_string("signature_hash");
    printf(": ");
    json_print_string(rec.signature_hash);
    printf(", ");
    json_print_string("declaration_hash");
    printf(": ");
    json_print_string(rec.declaration_hash);
    printf(", ");
    json_print_string("native_symbol");
    printf(": ");
    json_print_string(rec.native_symbol);
    printf(", ");
    json_print_string("fallback_descriptor");
    printf(": ");
    json_print_string(rec.fallback_descriptor);
    printf("}");
}

static bool json_print_call_relocation_array(const char* key,
        const std::vector<QoreAOTCallRelocationRecord>& records,
        unsigned indent, bool comma = true) {
    json_print_key(key, indent);
    printf("[");
    for (size_t i = 0; i < records.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT call-relocation JSON record dump")) {
            return false;
        }
        if (i) {
            printf(",");
        }
        printf("\n");
        json_print_call_relocation_record(records[i], indent + 2);
    }
    if (!records.empty()) {
        printf("\n%*s", static_cast<int>(indent), "");
    }
    printf("]%s\n", comma ? "," : "");
    return true;
}

static bool write_generated_file_if_changed(const std::string& path,
        const std::string& content, std::string& error);

static void append_aot_contract_field(std::string& row,
        const std::string& value) {
    row += std::to_string(value.size());
    row += ':';
    row += value;
}

static bool build_aot_contract_content(const QoreAOTSymbolIndex& index,
        std::string& compile_contract_content,
        std::string& compile_contract_hash, std::string& error) {
    std::vector<std::string> compile_rows;
    compile_rows.reserve(index.context.size() + index.defined.size()
        + index.native.size());
    std::set<std::string> required_namespaces;
    for (size_t i = 0; i < index.defined.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT compile-contract namespace collection")) {
            error = "operation cancelled during AOT compile-contract namespace collection";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = index.defined[i];
        if (rec.kind == QoreAOTSymbolKind::NAMESPACE) {
            continue;
        }
        size_t separator = rec.qore_path.find("::");
        while (separator != std::string::npos) {
            required_namespaces.insert(rec.qore_path.substr(0, separator));
            separator = rec.qore_path.find("::", separator + 2);
        }
    }
    for (size_t i = 0; i < index.context.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT context compile-contract collection")) {
            error = "operation cancelled during AOT context compile-contract collection";
            return false;
        }
        // Aggregate-only rows (declaration locations, digests of the declaration
        // records with their embedded defaults) affect the native-registration
        // aggregate, not the independently compiled source object's consumer
        // contract.
        if (!index.context[i].first.compare(0, 10, "aggregate_")) {
            continue;
        }
        std::string row = "context\t";
        append_aot_contract_field(row, index.context[i].first);
        append_aot_contract_field(row, index.context[i].second);
        compile_rows.push_back(std::move(row));
    }
    for (size_t i = 0; i < index.defined.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT compile-contract collection")) {
            error = "operation cancelled during AOT compile-contract collection";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = index.defined[i];
        // Per-file objects retain namespace context from the full parse or
        // preload program. Only namespace ancestors of symbols this object
        // actually defines are part of its consumer contract; recording the
        // complete ambient namespace set makes batch and single contracts
        // depend on unrelated sibling and loaded-module declarations.
        if (rec.kind == QoreAOTSymbolKind::NAMESPACE
                && !required_namespaces.count(rec.qore_path)) {
            continue;
        }
        std::string row = "defined\t";
        append_aot_contract_field(row, qoreAOTSymbolKindName(rec.kind));
        append_aot_contract_field(row,
            qoreAOTDependencyClassName(rec.dependency_class));
        append_aot_contract_field(row, std::to_string(rec.flags));
        append_aot_contract_field(row, rec.qore_path);
        append_aot_contract_field(row, rec.visibility);
        append_aot_contract_field(row, rec.signature_hash);
        append_aot_contract_field(row, rec.declaration_hash);
        append_aot_contract_field(row, rec.value_hash);
        append_aot_contract_field(row, rec.body_contract_hash);
        compile_rows.push_back(std::move(row));
    }
    for (size_t i = 0; i < index.native.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT native compile-contract collection")) {
            error = "operation cancelled during AOT native compile-contract collection";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = index.native[i];
        std::string row = "native\t";
        append_aot_contract_field(row,
            qoreAOTDependencyClassName(rec.dependency_class));
        append_aot_contract_field(row, std::to_string(rec.flags));
        append_aot_contract_field(row, rec.qore_path);
        append_aot_contract_field(row, rec.native_symbol);
        append_aot_contract_field(row, rec.abi_kind);
        append_aot_contract_field(row,
            std::to_string(rec.fast_entry_flags));
        append_aot_contract_field(row,
            std::to_string(rec.fast_entry_num_params));
        append_aot_contract_field(row,
            std::to_string(rec.fast_return_kind));
        append_aot_contract_field(row, rec.fast_specialization_key);
        append_aot_contract_field(row, rec.body_contract_hash);
        compile_rows.push_back(std::move(row));
    }
    std::sort(compile_rows.begin(), compile_rows.end());

    compile_contract_content = "format=1\n";
    for (size_t i = 0; i < compile_rows.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT compile-contract serialization")) {
            error = "operation cancelled during AOT compile-contract serialization";
            return false;
        }
        compile_contract_content += compile_rows[i];
        compile_contract_content.push_back('\n');
    }
    uint64_t compile_hash = XXH64(compile_contract_content.data(),
        compile_contract_content.size(), 0);
    compile_contract_hash = "xxh64:" + hex64_string(compile_hash);
    return true;
}

static bool write_aot_compile_contract_stamp_file(const char* stamp_path,
        const char* object_path, std::string& error) {
    QOLinkInputInfo input;
    if (!collect_qo_link_input(object_path, input, error)) {
        return false;
    }
    std::string content;
    std::string hash;
    if (!build_aot_contract_content(input.index, content, hash, error)) {
        return false;
    }
    return write_generated_file_if_changed(stamp_path, content, error);
}

static bool read_file_required(const std::string& path, std::string& content,
    std::string& error);

//! Builds the declaration contract of an object from its symbol index
/** @param index the object's symbol index
    @param content receives the contract
    @param contract_hash receives the contract's hash
    @param error receives the reason on failure
    @param aggregate_rows whether the rows only a script aggregate depends on are included: the declaration
    locations and the digests of the values its declaration records embed (context keys starting with
    \c aggregate_); the aggregate contract includes them, the declaration contract consumers depend on does not

    @return true on success, false if the operation was cancelled
*/
static bool build_aot_declaration_contract_content(
        const QoreAOTSymbolIndex& index, std::string& content,
        std::string& contract_hash, std::string& error, bool aggregate_rows) {
    std::vector<std::string> rows;
    rows.reserve(index.context.size() + index.defined.size());
    std::set<std::string> required_namespaces;
    for (size_t i = 0; i < index.defined.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT aggregate namespace collection")) {
            error = "operation cancelled during AOT aggregate namespace collection";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = index.defined[i];
        if (rec.kind == QoreAOTSymbolKind::NAMESPACE) {
            continue;
        }
        size_t separator = rec.qore_path.find("::");
        while (separator != std::string::npos) {
            required_namespaces.insert(rec.qore_path.substr(0, separator));
            separator = rec.qore_path.find("::", separator + 2);
        }
    }
    for (size_t i = 0; i < index.context.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT aggregate context-contract collection")) {
            error = "operation cancelled during AOT aggregate context-contract collection";
            return false;
        }
        // The feature bitset describes what this blob's LOWERING produced, not what its source declares:
        // computeFeatureFlags() ORs together the features of every function compiled into it, so a parse
        // that can lower a direct cross-source call advertises QORE_AOT_FEAT_FAST_CALL where a parse that
        // cannot does not.  It belongs with the native and body-contract rows this contract already omits
        // for the same reason -- keeping it made a batch compile and an equivalent standalone compile
        // spuriously disagree, which is what this contract exists not to do.
        if (index.context[i].first == "feature_flags") {
            continue;
        }
        // A consumer resolves against what a declaration is, not where it is or what values the aggregate
        // carries for it: a declaration that only moved to another line, or a member default, a default argument
        // or a base class argument that only changed its value, rebuilds the script aggregate and no consumer.
        if (!aggregate_rows && !index.context[i].first.compare(0, 10, "aggregate_")) {
            continue;
        }
        std::string row = "context\t";
        append_aot_contract_field(row, index.context[i].first);
        append_aot_contract_field(row, index.context[i].second);
        rows.push_back(std::move(row));
    }
    for (size_t i = 0; i < index.defined.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT aggregate declaration-contract collection")) {
            error = "operation cancelled during AOT aggregate declaration-contract collection";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = index.defined[i];
        if (rec.kind == QoreAOTSymbolKind::NAMESPACE
                && !required_namespaces.count(rec.qore_path)) {
            continue;
        }
        std::string row = "defined\t";
        append_aot_contract_field(row, qoreAOTSymbolKindName(rec.kind));
        append_aot_contract_field(row,
            qoreAOTDependencyClassName(rec.dependency_class));
        append_aot_contract_field(row, std::to_string(rec.flags));
        append_aot_contract_field(row, rec.qore_path);
        append_aot_contract_field(row, rec.source_file);
        append_aot_contract_field(row, rec.visibility);
        append_aot_contract_field(row, rec.signature_hash);
        append_aot_contract_field(row, rec.declaration_hash);
        append_aot_contract_field(row, rec.value_hash);
        rows.push_back(std::move(row));
    }
    std::sort(rows.begin(), rows.end());

    content = "format=1\n";
    for (size_t i = 0; i < rows.size(); ++i) {
        if (!json_dump_check_cancel(i,
                "AOT aggregate declaration-contract serialization")) {
            error = "operation cancelled during AOT aggregate declaration-contract serialization";
            return false;
        }
        content += rows[i];
        content.push_back('\n');
    }
    contract_hash = "xxh64:" + hex64_string(
        XXH64(content.data(), content.size(), 0));
    return true;
}

//! Build the content-preserving contract for a declaration-only script aggregate.
/** Native-register aggregates deserialize declarations once, then bind bodies,
    slot maps, init functions, statement locations, and debugger metadata from
    each linked per-source object. Their aggregate-visible per-source contract is
    therefore limited to canonical declarations, signatures, constant values,
    and parse context. Native capability and body-contract rows belong to the
    per-source object and final native link; including them here makes a batch
    compile and an equivalent standalone compile spuriously disagree. */
static bool build_aot_aggregate_contract_content(
        const std::vector<AOTDumpMetadataBlob>& blobs,
        const QoreAOTSymbolIndex& index,
        std::string& contract_content, std::string& contract_hash,
        std::string& error) {
    if (blobs.empty()) {
        error = "cannot build aggregate contract without AOT metadata";
        return false;
    }

    std::string declaration_content;
    std::string declaration_hash;
    if (!build_aot_declaration_contract_content(index, declaration_content,
            declaration_hash, error, true)) {
        return false;
    }

    for (size_t i = 0; i < blobs.size(); ++i) {
        if (i && !(i % 100)
                && qcc_check_cancel("AOT aggregate-contract collection")) {
            error = "operation cancelled during AOT aggregate-contract collection";
            return false;
        }
        QoreAOTBinaryReader reader;
        if (!reader.open(blobs[i].bytes.data(),
                static_cast<uint32_t>(blobs[i].bytes.size()), error)) {
            error = "invalid AOT metadata while building aggregate contract: " + error;
            return false;
        }
        const char* label = reader.getLabel();
        if (!label || !*label) {
            error = "AOT metadata has no source label while building aggregate contract";
            return false;
        }
    }

    contract_content = "format=3\ndeclarations\t" + declaration_hash + "\n";
    contract_hash = "xxh64:" + hex64_string(XXH64(
        contract_content.data(), contract_content.size(), 0));
    return true;
}

static bool write_aot_aggregate_contract_stamp_file(const char* stamp_path,
        const char* object_path, std::string& error) {
    std::vector<AOTDumpMetadataBlob> blobs;
    std::set<std::string> seen;
    collect_object_metadata_quiet(object_path, blobs, seen);

    std::string contents;
    if (!read_file_required(object_path, contents, error)) {
        return false;
    }
    scan_aot_metadata_blobs(contents, blobs, seen);

    QOLinkInputInfo input;
    if (!collect_qo_link_input(object_path, input, error)) {
        return false;
    }

    std::string contract_content;
    std::string contract_hash;
    if (!build_aot_aggregate_contract_content(blobs, input.index, contract_content,
            contract_hash, error)) {
        return false;
    }
    return write_generated_file_if_changed(stamp_path, contract_content, error);
}

//! Writes the declaration contract the consumers of an object depend on
/** This is the aggregate contract without the rows only the script aggregate depends on (see
    build_aot_declaration_contract_content()), so a declaration that only moved to another line, or a value
    that only the aggregate embeds, rebuilds the aggregate and no consumer.  Written with
    write_generated_file_if_changed(), so an unchanged contract keeps its mtime.

    @param stamp_path the stamp to write
    @param object_path the generated `.qo`
    @param error receives the reason on failure

    @return true on success, false with @a error set on failure
*/
static bool write_aot_declaration_contract_stamp_file(const char* stamp_path,
        const char* object_path, std::string& error) {
    QOLinkInputInfo input;
    if (!collect_qo_link_input(object_path, input, error)) {
        return false;
    }
    std::string declaration_content;
    std::string declaration_hash;
    if (!build_aot_declaration_contract_content(input.index, declaration_content,
            declaration_hash, error, false)) {
        return false;
    }
    return write_generated_file_if_changed(stamp_path,
        "format=1\ndeclarations\t" + declaration_hash + "\n", error);
}

//! Builds the body-contract half of an object's published interface.
/** The compile contract describes everything a compile produced; the declaration
    contract is the same description with the lowering artifacts left out, which is
    what makes it identical for a source compiled in a whole-group parse and the same
    source compiled standalone against shells.  This is the remainder: the
    body-contract hash of every symbol this object publishes one for.

    It exists because that remainder is not free to be ignored.  `--link-qo` compares
    a consumer's recorded import hash against the provider's published one and fails
    the aggregate with "qo-link hash mismatch" when they differ, so a consumer that
    baked a provider's BODY contract must be rebuilt when that hash moves -- and the
    declaration contract, by construction, cannot say that it did.  Measured on one
    875-source group: 856 objects publish a body contract, but only 280 consume one,
    from 25 providers.  Watching this from a consumer's generation is therefore
    precise; folding these hashes back into the declaration contract instead would
    make 856 of 877 objects mode-dependent again and restore the cascade in full.

    Only the symbol path and the hash are recorded.  A body-bearing symbol whose
    VALUE or declaration changed has already moved the declaration contract, and
    including the whole row here would make a consumer that fast-called one function
    rebuild for an unrelated change to another. */
static bool build_aot_body_contract_content(const QoreAOTSymbolIndex& index,
        std::string& content, std::string& error) {
    std::vector<std::string> rows;
    for (size_t i = 0; i < index.defined.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT body-contract collection")) {
            error = "operation cancelled during AOT body-contract collection";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = index.defined[i];
        if (rec.body_contract_hash.empty()) {
            continue;
        }
        std::string row = "body\t";
        append_aot_contract_field(row, rec.qore_path);
        append_aot_contract_field(row, rec.body_contract_hash);
        rows.push_back(std::move(row));
    }
    for (size_t i = 0; i < index.native.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT native body-contract collection")) {
            error = "operation cancelled during AOT native body-contract collection";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = index.native[i];
        if (rec.body_contract_hash.empty()) {
            continue;
        }
        // A fast entry publishes its body contract under the native symbol as well
        // as the Qore path: an ABI a consumer called directly is validated the same
        // way a source-level import is.
        std::string row = "native-body\t";
        append_aot_contract_field(row, rec.qore_path);
        append_aot_contract_field(row, rec.native_symbol);
        append_aot_contract_field(row, rec.body_contract_hash);
        rows.push_back(std::move(row));
    }
    std::sort(rows.begin(), rows.end());
    content = "format=1\n";
    for (size_t i = 0; i < rows.size(); ++i) {
        content += rows[i];
        content.push_back('\n');
    }
    return true;
}

static bool write_aot_body_contract_stamp_file(const char* stamp_path,
        const char* object_path, std::string& error) {
    QOLinkInputInfo input;
    if (!collect_qo_link_input(object_path, input, error)) {
        return false;
    }
    std::string content;
    if (!build_aot_body_contract_content(input.index, content, error)) {
        return false;
    }
    return write_generated_file_if_changed(stamp_path, content, error);
}

static int dump_aot_index_json_for_file(const char* path) {
    json_output_cancelled = false;
    std::vector<AOTDumpMetadataBlob> blobs;
    std::set<std::string> seen;
    collect_object_metadata_quiet(path, blobs, seen);

    std::string contents;
    if (!read_file(path, contents)) {
        return 1;
    }
    scan_aot_metadata_blobs(contents, blobs, seen);

    QoreAOTSymbolIndex combined;
    combined.version = QORE_AOT_SYMBOL_INDEX_VERSION;
    std::vector<QoreAOTCallRelocationRecord> call_relocations;
    std::vector<std::string> source_text;
    std::set<std::string> source_seen;
    for (size_t i = 0; i < blobs.size(); ++i) {
        if (i && !(i % 100) && qcc_check_cancel("AOT symbol-index JSON dump")) {
            fprintf(stderr, "error: operation cancelled during AOT symbol-index JSON dump\n");
            return 1;
        }
        QoreAOTBinaryReader reader;
        std::string error;
        if (!reader.open(blobs[i].bytes.data(), static_cast<uint32_t>(blobs[i].bytes.size()), error)) {
            fprintf(stderr, "error: invalid AOT metadata in '%s': %s\n", path, error.c_str());
            return 1;
        }
        const char* label = reader.getLabel();
        if (label && source_seen.insert(label).second) {
            source_text.emplace_back(label);
        }
        QoreAOTCallRelocations relocs;
        if (!readCallRelocations(reader, relocs, error)) {
            fprintf(stderr, "error: invalid CALL_RELOCATIONS in '%s': %s\n", path, error.c_str());
            return 1;
        }
        if (relocs.version) {
            call_relocations.insert(call_relocations.end(), relocs.records.begin(), relocs.records.end());
        }
        QoreAOTSymbolIndex index;
        if (!readSymbolIndex(reader, index, error)) {
            fprintf(stderr, "error: invalid SYMBOL_INDEX in '%s': %s\n", path, error.c_str());
            return 1;
        }
        if (!index.version) {
            continue;
        }
        combined.context.insert(combined.context.end(), index.context.begin(), index.context.end());
        combined.defined.insert(combined.defined.end(), index.defined.begin(), index.defined.end());
        combined.imported.insert(combined.imported.end(), index.imported.begin(), index.imported.end());
        combined.native.insert(combined.native.end(), index.native.begin(), index.native.end());
    }

    uint64_t object_hash = XXH64(contents.data(), contents.size(), 0);
    std::string hash = "xxh64:" + hex64_string(object_hash);
    std::vector<std::string> source_parse_defines;
    if (!json_collect_context_values(combined.context, "source_parse_define", source_parse_defines)) {
        return 1;
    }
    std::string compile_contract_content;
    std::string compile_contract_hash;
    std::string contract_error;
    if (!build_aot_contract_content(combined, compile_contract_content,
            compile_contract_hash, contract_error)) {
        fprintf(stderr, "error: %s\n", contract_error.c_str());
        return 1;
    }

    printf("{\n");
    json_print_u64_field("format", 1, 2);
    json_print_string_field("output", path, 2);
    json_print_string_field("object_hash", hash, 2);
    json_print_u64_field("object_size", contents.size(), 2);
    json_print_string_field("source", source_text.empty() ? "" : source_text.front(), 2);
    if (!json_print_string_array("source_text", source_text, 2)
            || !json_print_string_array("source_parse_defines", source_parse_defines, 2)
            || !json_print_context_array("context", combined.context, 2)
            || !json_print_symbol_array("defines", combined.defined, 2)
            || !json_print_symbol_array("provides", combined.defined, 2)
            || !json_print_symbol_array("requires", combined.imported, 2)
            || !json_print_symbol_array("native", combined.native, 2)
            || !json_print_call_relocation_array("call_relocations", call_relocations, 2)) {
        return 1;
    }
    json_print_string_field("native_body_hash", hash, 2);
    json_print_string_field("compile_contract_hash", compile_contract_hash,
        2, false);
    if (json_output_cancelled) {
        return 1;
    }
    printf("}\n");
    return blobs.empty() ? 1 : 0;
}

static bool write_generated_file_if_changed(const std::string& path,
        const std::string& content, std::string& error) {
    std::string old;
    if (is_file(path) && read_file(path.c_str(), old) && old == content) {
        return true;
    }

    std::string dir = dirname_of(path);
    if (dir.empty()) {
        dir = ".";
    }
    std::string pattern = dir + "/." + basename_no_ext(path) + ".tmp.XXXXXX";
    std::vector<char> tmp(pattern.begin(), pattern.end());
    tmp.push_back('\0');
    int fd = mkstemp(tmp.data());
    if (fd < 0) {
        error = "cannot create temporary file for '" + path + "': " + strerror(errno);
        return false;
    }
    FILE* f = fdopen(fd, "wb");
    if (!f) {
        int e = errno;
        close(fd);
        unlink(tmp.data());
        error = "cannot open temporary file for '" + path + "': " + strerror(e);
        return false;
    }
    if (!content.empty()
            && fwrite(content.data(), 1, content.size(), f) != content.size()) {
        int e = errno;
        fclose(f);
        unlink(tmp.data());
        error = "cannot write temporary file for '" + path + "': " + strerror(e);
        return false;
    }
    if (fclose(f) != 0) {
        int e = errno;
        unlink(tmp.data());
        error = "cannot close temporary file for '" + path + "': " + strerror(e);
        return false;
    }
    if (rename(tmp.data(), path.c_str()) != 0) {
        int e = errno;
        unlink(tmp.data());
        error = "cannot replace '" + path + "': " + strerror(e);
        return false;
    }
    return true;
}

static bool read_file_required(const std::string& path, std::string& content,
        std::string& error) {
    FILE* f = fopen(path.c_str(), "rb");
    if (!f) {
        error = "cannot open '" + path + "': " + strerror(errno);
        return false;
    }
    if (fseek(f, 0, SEEK_END) != 0) {
        error = "cannot seek '" + path + "': " + strerror(errno);
        fclose(f);
        return false;
    }
    long fsize = ftell(f);
    if (fsize < 0) {
        error = "cannot get size of '" + path + "': " + strerror(errno);
        fclose(f);
        return false;
    }
    if (fseek(f, 0, SEEK_SET) != 0) {
        error = "cannot seek '" + path + "': " + strerror(errno);
        fclose(f);
        return false;
    }
    content.resize(static_cast<size_t>(fsize));
    if (fsize > 0
            && fread(&content[0], 1, static_cast<size_t>(fsize), f) != static_cast<size_t>(fsize)) {
        error = "cannot read '" + path + "': " + strerror(errno);
        fclose(f);
        content.clear();
        return false;
    }
    if (fclose(f) != 0) {
        error = "cannot close '" + path + "': " + strerror(errno);
        content.clear();
        return false;
    }
    return true;
}

static std::string canonical_existing_path(const std::string& path) {
    char* resolved = realpath(path.c_str(), nullptr);
    if (!resolved) {
        return path;
    }
    std::string rv = resolved;
    free(resolved);
    return rv;
}

//! Returns the canonical form of a --file-prefix-map OLD prefix
/** qcc names its inputs, and so the source paths it emits, by their canonical paths, so a prefix that names them
    through a symbolic link (on macOS /tmp and /var are links to /private/tmp and /private/var) or with a relative path
    matches none of them.  The longest leading part of the prefix that names an existing path is made canonical, and
    the rest of the prefix is kept as it is: like the compiler's -ffile-prefix-map, a prefix is a string, which need not
    end at a path component.

    @param prefix the prefix as given

    @return the canonical form of the prefix; the prefix itself when no leading part of it can be resolved
*/
static std::string canonical_file_prefix(const std::string& prefix) {
    std::string head = prefix;
    // the rest of the prefix after head, which starts with a separator; trailing separators stay in it, so that
    // "dir/" maps "dir/file" and not "dirfile"
    std::string tail;
    while (head.size() > 1 && head.back() == '/') {
        head.pop_back();
        tail.insert(0, 1, '/');
    }
    while (true) {
        std::unique_ptr<char, decltype(&free)> resolved(realpath(head.c_str(), nullptr), &free);
        if (resolved) {
            std::string rv = resolved.get();
            // the canonical form of "/" ends with the separator that starts the rest
            if (!rv.empty() && rv.back() == '/' && !tail.empty()) {
                rv.pop_back();
            }
            return rv + tail;
        }
        size_t separator = head.find_last_of('/');
        if (separator == std::string::npos) {
            // a relative prefix whose first component does not exist names a path in the working directory
            std::unique_ptr<char, decltype(&free)> cwd(realpath(".", nullptr), &free);
            if (!cwd) {
                return prefix;
            }
            std::string rv = cwd.get();
            if (rv.back() != '/') {
                rv += '/';
            }
            return rv + head + tail;
        }
        tail.insert(0, head, separator, std::string::npos);
        head.erase(separator);
        if (head.empty()) {
            // no component of the absolute prefix exists
            return prefix;
        }
    }
}

//! Returns the --file-prefix-map maps with the canonical form of each OLD prefix that differs from it
/** Each canonical form follows the map it was made from, so the last matching map still wins.
*/
static std::vector<std::pair<std::string, std::string>> with_canonical_file_prefixes(
        const std::vector<std::pair<std::string, std::string>>& maps) {
    std::vector<std::pair<std::string, std::string>> rv;
    rv.reserve(maps.size() * 2);
    for (const auto& map : maps) {
        rv.push_back(map);
        std::string canonical = canonical_file_prefix(map.first);
        if (canonical != map.first) {
            rv.emplace_back(std::move(canonical), map.second);
        }
    }
    return rv;
}

static bool load_depfile_source_content_map(std::string& error) {
    if (!depfile_source_content_map_path) {
        return true;
    }

    std::string content;
    if (!read_file_required(depfile_source_content_map_path, content, error)) {
        return false;
    }
    size_t line_number = 0;
    for (size_t offset = 0; offset < content.size();) {
        size_t end = content.find('\n', offset);
        if (end == std::string::npos) {
            end = content.size();
        }
        ++line_number;
        if (!(line_number % 100)
                && qcc_check_cancel("qcc source-content map read")) {
            error = "operation cancelled while reading source-content map '"
                + std::string(depfile_source_content_map_path) + "'";
            return false;
        }
        std::string line = content.substr(offset, end - offset);
        if (!line.empty() && line.back() == '\r') {
            line.pop_back();
        }
        offset = end == content.size() ? end : end + 1;
        if (line.empty()) {
            continue;
        }
        size_t separator = line.find('\t');
        if (separator == std::string::npos || !separator
                || separator + 1 == line.size()
                || line.find('\t', separator + 1) != std::string::npos) {
            error = "invalid source-content map entry at line "
                + std::to_string(line_number) + " in '"
                + depfile_source_content_map_path + "'";
            return false;
        }
        std::string source = canonical_existing_path(
            line.substr(0, separator));
        std::string stamp = canonical_existing_path(
            line.substr(separator + 1));
        if (!depfile_dependency_exists(source)) {
            error = "source-content map source does not exist: '" + source
                + "'";
            return false;
        }
        if (!depfile_dependency_exists(stamp)) {
            error = "source-content map digest does not exist: '" + stamp
                + "'";
            return false;
        }
        auto inserted = depfile_source_content_stamps.emplace(source, stamp);
        if (!inserted.second && inserted.first->second != stamp) {
            error = "conflicting source-content map entries for '" + source
                + "'";
            return false;
        }
    }
    return true;
}

static QoreAOTSourceSymbolMap* source_symbol_map_for_kind(QoreAOTSourceSymbolManifest& manifest,
        const std::string& kind) {
    if (kind == "class") {
        return &manifest.classes;
    }
    if (kind == "hashdecl") {
        return &manifest.hashdecls;
    }
    if (kind == "function") {
        return &manifest.functions;
    }
    if (kind == "global") {
        return &manifest.globals;
    }
    if (kind == "typedef") {
        return &manifest.typedefs;
    }
    return nullptr;
}

static bool read_source_symbol_manifest(const char* path, QoreAOTSourceSymbolManifest& manifest,
        std::string& error) {
    if (!path || !*path) {
        return true;
    }
    std::string contents;
    if (!read_file(path, contents)) {
        error = std::string("cannot read source-symbol manifest: ") + path;
        return false;
    }

    size_t line_no = 0;
    size_t pos = 0;
    bool saw_format = false;
    while (pos <= contents.size()) {
        size_t end = contents.find('\n', pos);
        std::string line = end == std::string::npos
            ? contents.substr(pos)
            : contents.substr(pos, end - pos);
        if (!line.empty() && line.back() == '\r') {
            line.pop_back();
        }
        ++line_no;
        if (!(line_no % 100) && qore_check_cancel(nullptr, "qcc source-symbol manifest read")) {
            error = "operation cancelled during qcc source-symbol manifest read";
            return false;
        }
        pos = end == std::string::npos ? contents.size() + 1 : end + 1;

        if (line.empty() || line[0] == '#') {
            continue;
        }
        if (!saw_format) {
            if (line != "format=1") {
                error = "invalid source-symbol manifest '" + std::string(path)
                    + "': expected format=1 on line " + std::to_string(line_no);
                return false;
            }
            saw_format = true;
            continue;
        }

        size_t tab1 = line.find('\t');
        size_t tab2 = tab1 == std::string::npos ? std::string::npos : line.find('\t', tab1 + 1);
        if (tab1 == std::string::npos || tab2 == std::string::npos || tab2 + 1 >= line.size()) {
            error = "invalid source-symbol manifest '" + std::string(path)
                + "': malformed line " + std::to_string(line_no);
            return false;
        }
        std::string kind = line.substr(0, tab1);
        std::string symbol = line.substr(tab1 + 1, tab2 - tab1 - 1);
        std::string source = line.substr(tab2 + 1);
        if (symbol.empty() || source.empty()) {
            error = "invalid source-symbol manifest '" + std::string(path)
                + "': empty symbol or source on line " + std::to_string(line_no);
            return false;
        }
        QoreAOTSourceSymbolMap* map = source_symbol_map_for_kind(manifest, kind);
        if (!map) {
            error = "invalid source-symbol manifest '" + std::string(path)
                + "': unknown symbol kind '" + kind + "' on line " + std::to_string(line_no);
            return false;
        }
        (*map)[symbol].insert(canonical_existing_path(source));
    }
    if (!saw_format) {
        error = "invalid source-symbol manifest '" + std::string(path) + "': missing format=1";
        return false;
    }
    return true;
}

static bool write_json_file_string_field(FILE* f, const char* key,
        const std::string& value, unsigned indent, const char* comma = ",") {
    fprintf(f, "%*s", static_cast<int>(indent), "");
    json_file_string(f, key ? key : "");
    fputs(": ", f);
    json_file_string(f, value);
    fprintf(f, "%s\n", comma);
    return true;
}

static bool write_json_file_u64_field(FILE* f, const char* key, uint64_t value,
        unsigned indent, const char* comma = ",") {
    fprintf(f, "%*s", static_cast<int>(indent), "");
    json_file_string(f, key ? key : "");
    fprintf(f, ": %llu%s\n", static_cast<unsigned long long>(value), comma);
    return true;
}

static bool write_json_file_bool_field(FILE* f, const char* key, bool value,
        unsigned indent, const char* comma = ",") {
    fprintf(f, "%*s", static_cast<int>(indent), "");
    json_file_string(f, key ? key : "");
    fprintf(f, ": %s%s\n", value ? "true" : "false", comma);
    return true;
}

struct QCCFileFingerprint {
    bool exists = false;
    uint64_t size = 0;
    uint64_t hash = 0;
};

static bool write_json_file_record(FILE* f, const char* key, const std::string& path,
        unsigned indent, std::string& error, const char* comma = ",") {
    std::string contents;
    if (!read_file_required(path, contents, error)) {
        return false;
    }
    uint64_t hash = XXH64(contents.data(), contents.size(), 0);
    fprintf(f, "%*s", static_cast<int>(indent), "");
    json_file_string(f, key ? key : "");
    fputs(": {\"path\": ", f);
    json_file_string(f, canonical_existing_path(path));
    fprintf(f, ", \"size\": %llu, \"hash\": ",
        static_cast<unsigned long long>(contents.size()));
    json_file_string(f, "xxh64:" + hex64_string(hash));
    fprintf(f, "}%s\n", comma);
    return true;
}

static bool write_json_file_record_array(FILE* f, const char* key,
        const std::vector<std::string>& paths, unsigned indent, std::string& error,
        const char* comma = ",",
        const std::map<std::string, QCCFileFingerprint>* input_snapshots = nullptr) {
    fprintf(f, "%*s", static_cast<int>(indent), "");
    json_file_string(f, key ? key : "");
    fputs(": [", f);
    std::set<std::string> seen;
    std::vector<std::string> canonical_paths;
    for (size_t i = 0; i < paths.size(); ++i) {
        if (!json_dump_check_cancel(i, "qcc manifest input write")) {
            error = "operation cancelled during qcc manifest input write";
            return false;
        }
        if (paths[i].empty() || !is_file(paths[i])) {
            continue;
        }
        std::string canon = canonical_existing_path(paths[i]);
        if (!seen.insert(canon).second) {
            continue;
        }
        canonical_paths.push_back(std::move(canon));
    }
    std::sort(canonical_paths.begin(), canonical_paths.end());
    size_t written = 0;
    for (size_t i = 0; i < canonical_paths.size(); ++i) {
        if (!json_dump_check_cancel(i, "qcc manifest canonical input write")) {
            error = "operation cancelled during qcc manifest canonical input write";
            return false;
        }
        QCCFileFingerprint fp;
        bool have_snapshot = false;
        if (input_snapshots) {
            auto snapshot = input_snapshots->find(canonical_paths[i]);
            if (snapshot != input_snapshots->end()) {
                fp = snapshot->second;
                have_snapshot = true;
            }
        }
        if (!have_snapshot) {
            std::string contents;
            if (!read_file_required(canonical_paths[i], contents, error)) {
                return false;
            }
            fp.exists = true;
            fp.size = contents.size();
            fp.hash = XXH64(contents.data(), contents.size(), 0);
        }
        if (written++) {
            fputc(',', f);
        }
        fprintf(f, "\n%*s{\"path\": ", static_cast<int>(indent + 2), "");
        json_file_string(f, canonical_paths[i]);
        fprintf(f, ", \"size\": %llu, \"hash\": ",
            static_cast<unsigned long long>(fp.size));
        json_file_string(f, "xxh64:" + hex64_string(fp.hash));
        fputc('}', f);
    }
    if (written) {
        fprintf(f, "\n%*s", static_cast<int>(indent), "");
    }
    fprintf(f, "]%s\n", comma);
    return true;
}

static bool json_file_context_array_for_index(FILE* f, const char* key,
        const std::vector<std::pair<std::string, std::string>>& values,
        std::string& error, const char* comma = ",") {
    fprintf(f, "  \"%s\": [", key);
    for (size_t i = 0; i < values.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT symbol-index JSON context write")) {
            error = "operation cancelled during AOT symbol-index JSON context write";
            return false;
        }
        if (i) {
            fputc(',', f);
        }
        fputs("\n    {\"key\": ", f);
        json_file_string(f, values[i].first);
        fputs(", \"value\": ", f);
        json_file_string(f, values[i].second);
        fputc('}', f);
    }
    if (!values.empty()) {
        fputs("\n  ", f);
    }
    fprintf(f, "]%s\n", comma);
    return true;
}

static bool json_file_symbol_array_for_index(FILE* f, const char* key,
        const std::vector<QoreAOTSymbolIndexRecord>& records,
        std::string& error, const char* comma = ",") {
    fprintf(f, "  \"%s\": [", key);
    for (size_t i = 0; i < records.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT symbol-index JSON record write")) {
            error = "operation cancelled during AOT symbol-index JSON record write";
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = records[i];
        if (i) {
            fputc(',', f);
        }
        fputs("\n    {\"kind\": ", f);
        json_file_string(f, qoreAOTSymbolKindName(rec.kind));
        fputs(", \"dependency_class\": ", f);
        json_file_string(f, qoreAOTDependencyClassName(rec.dependency_class));
        fprintf(f, ", \"flags\": %u, \"metadata_slot\": ", rec.flags);
        if (rec.metadata_slot == UINT32_MAX) {
            fputs("null", f);
        } else {
            fprintf(f, "%u", rec.metadata_slot);
        }
        fputs(", \"qore_path\": ", f);
        json_file_string(f, rec.qore_path);
        fputs(", \"source_file\": ", f);
        json_file_string(f, rec.source_file);
        fputs(", \"visibility\": ", f);
        json_file_string(f, rec.visibility);
        fputs(", \"signature_hash\": ", f);
        json_file_string(f, rec.signature_hash);
        fputs(", \"declaration_hash\": ", f);
        json_file_string(f, rec.declaration_hash);
        fputs(", \"value_hash\": ", f);
        json_file_string(f, rec.value_hash);
        fputs(", \"body_contract_hash\": ", f);
        json_file_string(f, rec.body_contract_hash);
        fputs(", \"native_symbol\": ", f);
        json_file_string(f, rec.native_symbol);
        fputs(", \"abi_kind\": ", f);
        json_file_string(f, rec.abi_kind);
        fputs(", \"consumer_source_file\": ", f);
        json_file_string(f, rec.consumer_source_file);
        fputs(", \"provider_source_file\": ", f);
        json_file_string(f, rec.provider_source_file);
        fprintf(f, ", \"fast_entry_flags\": %u, \"fast_entry_num_params\": %u, \"fast_return_kind\": %u",
            rec.fast_entry_flags, rec.fast_entry_num_params, rec.fast_return_kind);
        fputs(", \"fast_specialization_key\": ", f);
        json_file_string(f, rec.fast_specialization_key);
        auto write_bytes = [f](const char* name, const std::vector<uint8_t>& values) {
            fprintf(f, ", \"%s\": [", name);
            for (size_t j = 0; j < values.size(); ++j) {
                if (j && !(j % 100)
                        && qcc_check_cancel("AOT fast-entry parameter JSON write")) {
                    break;
                }
                fprintf(f, "%s%u", j ? ", " : "", values[j]);
            }
            fputc(']', f);
        };
        write_bytes("fast_param_kinds", rec.fast_param_kinds);
        write_bytes("fast_param_rejects_nothing", rec.fast_param_rejects_nothing);
        write_bytes("fast_param_noescape", rec.fast_param_noescape);
        write_bytes("fast_param_may_modify", rec.fast_param_may_modify);
        fprintf(f, ", \"scalar_leaf_kind\": %u, \"scalar_leaf_opcode\": %u"
            ", \"scalar_leaf_lhs_param\": %d, \"scalar_leaf_rhs_param\": %d"
            ", \"scalar_leaf_lhs_int\": " QLLD ", \"scalar_leaf_rhs_int\": " QLLD
            ", \"scalar_leaf_lhs_float\": %.17g, \"scalar_leaf_rhs_float\": %.17g"
            ", \"scalar_leaf_true_scale\": " QLLD ", \"scalar_leaf_true_offset\": " QLLD
            ", \"scalar_leaf_false_scale\": " QLLD ", \"scalar_leaf_false_offset\": " QLLD
            ", \"object_getter_member\": ",
            rec.scalar_leaf_kind, rec.scalar_leaf_opcode,
            rec.scalar_leaf_lhs_param, rec.scalar_leaf_rhs_param,
            static_cast<long long>(rec.scalar_leaf_lhs_int),
            static_cast<long long>(rec.scalar_leaf_rhs_int),
            rec.scalar_leaf_lhs_float, rec.scalar_leaf_rhs_float,
            static_cast<long long>(rec.scalar_leaf_true_scale),
            static_cast<long long>(rec.scalar_leaf_true_offset),
            static_cast<long long>(rec.scalar_leaf_false_scale),
            static_cast<long long>(rec.scalar_leaf_false_offset));
        json_file_string(f, rec.object_getter_member);
        fputs(", \"object_set_get_member\": ", f);
        json_file_string(f, rec.object_set_get_member);
        fprintf(f, ", \"object_set_get_param\": %d",
            rec.object_set_get_param);
        fputs(", \"object_compound_get_member\": ", f);
        json_file_string(f, rec.object_compound_get_member);
        fprintf(f, ", \"object_compound_get_param\": %d"
            ", \"object_compound_get_op\": %u",
            rec.object_compound_get_param, rec.object_compound_get_op);
        fprintf(f, ", \"string_op_kind\": %u, \"string_op_base_param\": %d"
            ", \"string_op_arg0_param\": %d, \"string_op_arg1_param\": %d",
            rec.string_op_kind, rec.string_op_base_param,
            rec.string_op_arg0_param, rec.string_op_arg1_param);
        fprintf(f, ", \"collection_op_kind\": %u, \"collection_op_base_param\": %d"
            ", \"collection_op_index_param\": %d, \"collection_op_string_index_char\": %s"
            ", \"collection_op_key\": ", rec.collection_op_kind,
            rec.collection_op_base_param, rec.collection_op_index_param,
            rec.collection_op_string_index_char ? "true" : "false");
        json_file_string(f, rec.collection_op_key);
        fprintf(f,
            ", \"aggregate_return_kind\": %u, \"aggregate_return_value_params\": [",
            rec.aggregate_return_kind);
        for (size_t j = 0;
                j < rec.aggregate_return_value_params.size(); ++j) {
            fprintf(f, "%s%d", j ? ", " : "",
                rec.aggregate_return_value_params[j]);
        }
        fputs("], \"aggregate_return_value_kinds\": [", f);
        for (size_t j = 0;
                j < rec.aggregate_return_value_kinds.size(); ++j) {
            fprintf(f, "%s%u", j ? ", " : "",
                rec.aggregate_return_value_kinds[j]);
        }
        fputs("], \"aggregate_return_value_ints\": [", f);
        for (size_t j = 0;
                j < rec.aggregate_return_value_ints.size(); ++j) {
            fprintf(f, "%s" QLLD, j ? ", " : "",
                static_cast<long long>(
                    rec.aggregate_return_value_ints[j]));
        }
        fputs("], \"aggregate_return_value_floats\": [", f);
        for (size_t j = 0;
                j < rec.aggregate_return_value_floats.size(); ++j) {
            fprintf(f, "%s%.17g", j ? ", " : "",
                rec.aggregate_return_value_floats[j]);
        }
        fputs("], \"aggregate_return_keys\": [", f);
        for (size_t j = 0; j < rec.aggregate_return_keys.size(); ++j) {
            if (j) {
                fputs(", ", f);
            }
            json_file_string(f, rec.aggregate_return_keys[j]);
        }
        fprintf(f, "], \"aggregate_return_shape_condition_param\": %d"
            ", \"aggregate_return_shape_true_size\": %u"
            ", \"aggregate_return_shape_false_size\": %u"
            ", \"aggregate_return_value_selects\": [",
            rec.aggregate_return_shape_condition_param,
            rec.aggregate_return_shape_true_size,
            rec.aggregate_return_shape_false_size);
        for (size_t j = 0;
                j < rec.aggregate_return_value_selects.size(); ++j) {
            const auto& select =
                rec.aggregate_return_value_selects[j];
            fprintf(f,
                "%s{\"value_index\": %u, \"condition_param\": %d"
                ", \"true_kind\": %u, \"true_param\": %d"
                ", \"true_int\": " QLLD ", \"true_float\": %.17g"
                ", \"false_kind\": %u, \"false_param\": %d"
                ", \"false_int\": " QLLD
                ", \"false_float\": %.17g}",
                j ? ", " : "", select.value_index,
                select.condition_param, select.true_value.kind,
                select.true_value.param,
                static_cast<long long>(
                    select.true_value.int_value),
                select.true_value.float_value,
                select.false_value.kind,
                select.false_value.param,
                static_cast<long long>(
                    select.false_value.int_value),
                select.false_value.float_value);
        }
        fprintf(f,
            "], \"boxed_return_param\": %d, \"boxed_return_kind\": %u",
            rec.boxed_return_param, rec.boxed_return_kind);
        fprintf(f, ", \"composed_int_source_kind\": %u, \"composed_int_base_param\": %d"
            ", \"composed_int_value_param\": %d, \"composed_int_source_scale\": " QLLD
            ", \"composed_int_value_scale\": " QLLD ", \"composed_int_offset\": " QLLD,
            rec.composed_int_source_kind, rec.composed_int_base_param,
            rec.composed_int_value_param,
            static_cast<long long>(rec.composed_int_source_scale),
            static_cast<long long>(rec.composed_int_value_scale),
            static_cast<long long>(rec.composed_int_offset));
        fprintf(f, ", \"global_int_value_param\": %d, \"global_int_slot\": %d"
            ", \"global_int_value_scale\": " QLLD ", \"global_int_global_scale\": " QLLD
            ", \"global_int_offset\": " QLLD,
            rec.global_int_value_param, rec.global_int_slot,
            static_cast<long long>(rec.global_int_value_scale),
            static_cast<long long>(rec.global_int_global_scale),
            static_cast<long long>(rec.global_int_offset));
        fputs(", \"int_expression_nodes\": [", f);
        for (size_t j = 0; j < rec.int_expression_nodes.size(); ++j) {
            const auto& node = rec.int_expression_nodes[j];
            fprintf(f, "%s{\"kind\": %u, \"lhs\": %u, \"rhs\": %u, \"third\": %u, \"param\": %d"
                ", \"constant\": " QLLD ", \"key\": ", j ? ", " : "", node.kind,
                node.lhs, node.rhs, node.third, node.param,
                static_cast<long long>(node.constant));
            json_file_string(f, node.key);
            fputc('}', f);
        }
        fputc(']', f);
        fputs(", \"float_expression_nodes\": [", f);
        for (size_t j = 0; j < rec.float_expression_nodes.size(); ++j) {
            const auto& node = rec.float_expression_nodes[j];
            fprintf(f, "%s{\"kind\": %u, \"lhs\": %u, \"rhs\": %u, \"param\": %d"
                ", \"constant\": %.17g, \"key\": ", j ? ", " : "", node.kind,
                node.lhs, node.rhs, node.param, node.constant);
            json_file_string(f, node.key);
            fputc('}', f);
        }
        fputc(']', f);
        fputs(", \"string_expression_nodes\": [", f);
        for (size_t j = 0; j < rec.string_expression_nodes.size(); ++j) {
            const auto& node = rec.string_expression_nodes[j];
            fprintf(f, "%s{\"kind\": %u, \"lhs\": %u, \"rhs\": %u, \"third\": %u"
                ", \"param\": %d, \"int_constant\": " QLLD
                ", \"string_constant\": ", j ? ", " : "", node.kind,
                node.lhs, node.rhs, node.third, node.param,
                static_cast<long long>(node.int_constant));
            json_file_string(f, node.string_constant);
            fputc('}', f);
        }
        fputc(']', f);
        fputs(", \"body_dependency_files\": [", f);
        for (size_t j = 0; j < rec.body_dependency_files.size(); ++j) {
            if (j && !(j % 100)
                    && qcc_check_cancel(
                        "AOT body dependency sidecar output")) {
                error = "AOT body dependency sidecar output cancelled";
                return false;
            }
            if (j) {
                fputs(", ", f);
            }
            json_file_string(f, rec.body_dependency_files[j]);
        }
        fputc(']', f);
        fputs(", \"body_contract_dependencies\": [", f);
        for (size_t j = 0;
                j < rec.body_contract_dependencies.size(); ++j) {
            if (j && !(j % 100)
                    && qcc_check_cancel(
                        "AOT body contract dependency sidecar output")) {
                error = "AOT body contract dependency sidecar output cancelled";
                return false;
            }
            if (j) {
                fputs(", ", f);
            }
            const auto& dependency =
                rec.body_contract_dependencies[j];
            fputs("{\"qore_path\": ", f);
            json_file_string(f, dependency.qore_path);
            fputs(", \"provider_source_file\": ", f);
            json_file_string(f, dependency.provider_source_file);
            fputs(", \"body_contract_hash\": ", f);
            json_file_string(f, dependency.body_contract_hash);
            fputc('}', f);
        }
        fputc(']', f);
        fputc('}', f);
    }
    if (!records.empty()) {
        fputs("\n  ", f);
    }
    fprintf(f, "]%s\n", comma);
    return true;
}

static bool json_file_call_relocations_for_index(FILE* f, const char* key,
        const std::vector<QoreAOTCallRelocationRecord>& records,
        std::string& error, const char* comma = ",") {
    fprintf(f, "  \"%s\": [", key);
    for (size_t i = 0; i < records.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT call-relocation JSON record write")) {
            error = "operation cancelled during AOT call-relocation JSON record write";
            return false;
        }
        const QoreAOTCallRelocationRecord& rec = records[i];
        if (i) {
            fputc(',', f);
        }
        fputs("\n    {\"function\": ", f);
        json_file_string(f, rec.function_name);
        fprintf(f, ", \"expr_slot\": %u, \"target_kind\": ", rec.expr_slot);
        json_file_string(f, qoreAOTCallRelocationTargetKindName(rec.target_kind));
        fputs(", \"strictness\": ", f);
        json_file_string(f, rec.strictness == QoreAOTCallRelocationStrictness::REQUIRED
            ? "required" : "optional");
        fputs(", \"qore_path\": ", f);
        json_file_string(f, rec.qore_path);
        fputs(", \"path\": ", f);
        json_file_string(f, rec.qore_path);
        fputs(", \"signature_hash\": ", f);
        json_file_string(f, rec.signature_hash);
        fputs(", \"declaration_hash\": ", f);
        json_file_string(f, rec.declaration_hash);
        fputs(", \"native_symbol\": ", f);
        json_file_string(f, rec.native_symbol);
        fputs(", \"fallback_descriptor\": ", f);
        json_file_string(f, rec.fallback_descriptor);
        fputc('}', f);
    }
    if (!records.empty()) {
        fputs("\n  ", f);
    }
    fprintf(f, "]%s\n", comma);
    return true;
}

static bool write_aot_index_json_stream(FILE* f, const char* path,
        bool allow_empty_metadata, std::string& error,
        std::string* compile_contract_content_out = nullptr,
        std::string* aggregate_contract_content_out = nullptr) {
    std::vector<AOTDumpMetadataBlob> blobs;
    std::set<std::string> seen;
    collect_object_metadata_quiet(path, blobs, seen);

    std::string contents;
    if (!read_file_required(path, contents, error)) {
        return false;
    }
    scan_aot_metadata_blobs(contents, blobs, seen);

    QoreAOTSymbolIndex combined;
    combined.version = QORE_AOT_SYMBOL_INDEX_VERSION;
    std::vector<QoreAOTCallRelocationRecord> call_relocations;
    std::vector<std::string> source_text;
    std::set<std::string> source_seen;
    for (size_t i = 0; i < blobs.size(); ++i) {
        if (!json_dump_check_cancel(i, "AOT symbol-index JSON write")) {
            error = "operation cancelled during AOT symbol-index JSON write";
            return false;
        }
        QoreAOTBinaryReader reader;
        if (!reader.open(blobs[i].bytes.data(), static_cast<uint32_t>(blobs[i].bytes.size()), error)) {
            error = "invalid AOT metadata in '" + std::string(path) + "': " + error;
            return false;
        }
        const char* label = reader.getLabel();
        if (label && source_seen.insert(label).second) {
            source_text.emplace_back(label);
        }
        QoreAOTCallRelocations relocs;
        if (!readCallRelocations(reader, relocs, error)) {
            error = "invalid CALL_RELOCATIONS in '" + std::string(path) + "': " + error;
            return false;
        }
        if (relocs.version) {
            call_relocations.insert(call_relocations.end(), relocs.records.begin(), relocs.records.end());
        }
        QoreAOTSymbolIndex index;
        if (!readSymbolIndex(reader, index, error)) {
            error = "invalid SYMBOL_INDEX in '" + std::string(path) + "': " + error;
            return false;
        }
        if (!index.version) {
            continue;
        }
        combined.context.insert(combined.context.end(), index.context.begin(), index.context.end());
        combined.defined.insert(combined.defined.end(), index.defined.begin(), index.defined.end());
        combined.imported.insert(combined.imported.end(), index.imported.begin(), index.imported.end());
        combined.native.insert(combined.native.end(), index.native.begin(), index.native.end());
    }

    uint64_t object_hash = XXH64(contents.data(), contents.size(), 0);
    std::string hash = "xxh64:" + hex64_string(object_hash);
    std::vector<std::string> source_parse_defines;
    if (!json_collect_context_values(combined.context, "source_parse_define", source_parse_defines)) {
        error = "operation cancelled during AOT symbol-index parse-define collection";
        return false;
    }
    std::string compile_contract_content;
    std::string compile_contract_hash;
    if (!build_aot_contract_content(combined, compile_contract_content,
            compile_contract_hash, error)) {
        return false;
    }
    std::string aggregate_contract_content;
    std::string aggregate_contract_hash;
    if (aggregate_contract_content_out
            && !build_aot_aggregate_contract_content(blobs, combined,
                aggregate_contract_content, aggregate_contract_hash, error)) {
        return false;
    }

    fputs("{\n", f);
    write_json_file_u64_field(f, "format", 1, 2);
    write_json_file_string_field(f, "output", path, 2);
    write_json_file_string_field(f, "object_hash", hash, 2);
    write_json_file_u64_field(f, "object_size", contents.size(), 2);
    write_json_file_string_field(f, "source", source_text.empty() ? "" : source_text.front(), 2);
    if (!json_file_string_array(f, "source_text", source_text, error)
            || !json_file_string_array(f, "source_parse_defines", source_parse_defines, error)
            || !json_file_context_array_for_index(f, "context", combined.context, error)
            || !json_file_symbol_array_for_index(f, "defines", combined.defined, error)
            || !json_file_symbol_array_for_index(f, "provides", combined.defined, error)
            || !json_file_symbol_array_for_index(f, "requires", combined.imported, error)
            || !json_file_symbol_array_for_index(f, "native", combined.native, error)
            || !json_file_call_relocations_for_index(f, "call_relocations", call_relocations, error)) {
        return false;
    }
    write_json_file_string_field(f, "native_body_hash", hash, 2);
    write_json_file_string_field(f, "compile_contract_hash",
        compile_contract_hash, 2);
    write_json_file_string_field(f, "aggregate_contract_hash",
        aggregate_contract_hash, 2, "");
    fputs("}\n", f);
    if (json_output_cancelled) {
        error = "operation cancelled during AOT symbol-index JSON write";
        return false;
    }
    if (blobs.empty() && !allow_empty_metadata) {
        error = "no AOT metadata found in '" + std::string(path) + "'";
        return false;
    }
    if (compile_contract_content_out) {
        *compile_contract_content_out = std::move(compile_contract_content);
    }
    if (aggregate_contract_content_out) {
        *aggregate_contract_content_out = std::move(aggregate_contract_content);
    }
    return true;
}

static bool write_aot_index_json_file(const char* index_path,
        const char* object_path, bool allow_empty_metadata, std::string& error,
        const char* contract_stamp_path = nullptr,
        const char* aggregate_contract_stamp_path = nullptr) {
    json_output_cancelled = false;
    char* buf = nullptr;
    size_t size = 0;
    FILE* f = open_memstream(&buf, &size);
    if (!f) {
        error = "cannot allocate AOT index JSON buffer: " + std::string(strerror(errno));
        return false;
    }
    std::string compile_contract_content;
    std::string aggregate_contract_content;
    bool ok = write_aot_index_json_stream(f, object_path,
        allow_empty_metadata, error, contract_stamp_path
            ? &compile_contract_content : nullptr,
        aggregate_contract_stamp_path ? &aggregate_contract_content : nullptr);
    if (fclose(f) != 0 && ok) {
        error = "cannot close AOT index JSON buffer: " + std::string(strerror(errno));
        ok = false;
    }
    std::string content;
    if (ok) {
        content.assign(buf, size);
    }
    free(buf);
    if (!ok) {
        return false;
    }
    if (index_path
            && !write_generated_file_if_changed(index_path, content, error)) {
        return false;
    }
    if (contract_stamp_path
            && !write_generated_file_if_changed(contract_stamp_path,
                compile_contract_content, error)) {
        return false;
    }
    return !aggregate_contract_stamp_path
        || write_generated_file_if_changed(aggregate_contract_stamp_path,
            aggregate_contract_content, error);
}

static void read_make_depfile_inputs(const std::string& depfile,
        std::vector<std::string>& out) {
    std::string text;
    if (!is_file(depfile) || !read_file(depfile.c_str(), text)) {
        return;
    }
    size_t pos = text.find(':');
    if (pos == std::string::npos) {
        return;
    }
    ++pos;
    std::string token;
    bool escaped = false;
    for (; pos < text.size(); ++pos) {
        char c = text[pos];
        if (escaped) {
            if (c != '\n') {
                token.push_back(c);
            }
            escaped = false;
            continue;
        }
        if (c == '\\') {
            escaped = true;
            continue;
        }
        if (std::isspace(static_cast<unsigned char>(c))) {
            if (!token.empty()) {
                out.push_back(token);
                token.clear();
            }
            continue;
        }
        token.push_back(c);
    }
    if (!token.empty()) {
        out.push_back(token);
    }
}

static bool add_aot_compile_contract_depfile_inputs(
        const std::string& depfile, std::vector<std::string>& inputs,
        std::string& error) {
    if (!depfile_compile_contract_stamps || depfile.empty()
            || !is_file(depfile)) {
        return true;
    }
    static constexpr const char suffix[] = ".compile-contract.stamp";
    // A declaration contract is a published provider interface exactly as a compile contract is,
    // so --skip-if-manifest-current has to watch it for the same reason: a provider whose
    // declarations moved must not let this object skip its own recompile.  Watch every such
    // prerequisite already present in the depfile, even when the current invocation no longer
    // emits declaration-contract dependencies: a depfile from an earlier configuration remains
    // authoritative until this invocation has actually rebuilt and replaced it.
    static constexpr const char declaration_suffix[] = ".declaration-contract.stamp";
    // the suffix consumers recorded before the declaration contract left out what only the script aggregate
    // depends on
    static constexpr const char legacy_declaration_suffix[] = ".aggregate-contract.stamp";
    std::vector<std::string> deps;
    read_make_depfile_inputs(depfile, deps);
    for (size_t i = 0; i < deps.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT compile-contract manifest input collection", error)) {
            return false;
        }
        if (deps[i].size() >= sizeof(suffix) - 1
                && deps[i].compare(deps[i].size() - (sizeof(suffix) - 1),
                    sizeof(suffix) - 1, suffix) == 0) {
            inputs.push_back(deps[i]);
            continue;
        }
        if ((deps[i].size() >= sizeof(declaration_suffix) - 1
                    && deps[i].compare(deps[i].size() - (sizeof(declaration_suffix) - 1),
                        sizeof(declaration_suffix) - 1, declaration_suffix) == 0)
                || (deps[i].size() >= sizeof(legacy_declaration_suffix) - 1
                    && deps[i].compare(deps[i].size() - (sizeof(legacy_declaration_suffix) - 1),
                        sizeof(legacy_declaration_suffix) - 1, legacy_declaration_suffix) == 0)) {
            inputs.push_back(deps[i]);
        }
    }
    return true;
}

static void collect_qo_library_inputs(std::vector<std::string>& out,
        const std::vector<std::string>& dirs, const std::string& output) {
    std::string output_canon = output.empty() ? "" : canonical_existing_path(output);
    for (const std::string& dir_path : dirs) {
        DIR* d = opendir(dir_path.c_str());
        if (!d) {
            continue;
        }
        struct dirent* ent;
        while ((ent = readdir(d)) != nullptr) {
            if (!has_qo_extension(ent->d_name)) {
                continue;
            }
            std::string path = dir_path + "/" + ent->d_name;
            std::string canon = canonical_existing_path(path);
            if (!output_canon.empty() && canon == output_canon) {
                continue;
            }
            out.push_back(canon);
        }
        closedir(d);
    }
}

static std::string resolve_command_path(const char* argv0) {
    if (!argv0 || !*argv0) {
        return "";
    }
    if (strchr(argv0, '/')) {
        return canonical_existing_path(argv0);
    }
    QoreEnvironmentValue path_env_holder("PATH");
    const char* path_env = path_env_holder.c_str();
    if (!path_env) {
        return argv0;
    }
    const char* start = path_env;
    for (const char* p = path_env; ; ++p) {
        if (*p == ':' || *p == '\0') {
            std::string dir(start, p - start);
            std::string candidate = (dir.empty() ? "." : dir) + "/" + argv0;
            if (access(candidate.c_str(), X_OK) == 0) {
                return canonical_existing_path(candidate);
            }
            if (*p == '\0') {
                break;
            }
            start = p + 1;
        }
    }
    return argv0;
}

struct QCCBuildManifest {
    std::string kind;
    std::string output;
    std::string index_json;
    std::string depfile;
    std::string link_map;
    std::string aggregate_symbol;
    std::vector<std::string> inputs;
    std::vector<std::string> extra_inputs;
    std::shared_ptr<const std::map<std::string, QCCFileFingerprint>> input_snapshots;
    std::shared_ptr<const std::map<std::string, QCCFileFingerprint>> observed_source_snapshots;
    bool include_command_manifest_inputs = true;
};

static QCCFileFingerprint qcc_file_fingerprint(const std::string& path) {
    QCCFileFingerprint rv;
    if (path.empty() || !is_file(path)) {
        return rv;
    }

    std::string contents;
    std::string error;
    if (!read_file_required(path, contents, error)) {
        return rv;
    }
    rv.exists = true;
    rv.size = contents.size();
    rv.hash = XXH64(contents.data(), contents.size(), 0);
    return rv;
}

static QCCFileFingerprint qcc_content_fingerprint(const std::string& contents) {
    QCCFileFingerprint rv;
    rv.exists = true;
    rv.size = contents.size();
    rv.hash = XXH64(contents.data(), contents.size(), 0);
    return rv;
}

static QCCFileFingerprint qcc_input_fingerprint(const std::string& path) {
    if (!is_directory(path.c_str())) {
        return qcc_file_fingerprint(path);
    }

    std::vector<std::string> sources;
    add_module_source_dir(path, sources);
    std::string names;
    for (const std::string& source : sources) {
        names.append(canonical_existing_path(source));
        names.push_back('\0');
    }
    QCCFileFingerprint rv = qcc_content_fingerprint(names);
    rv.size = sources.size();
    return rv;
}

static bool qcc_file_fingerprint_equal(const QCCFileFingerprint& a,
        const QCCFileFingerprint& b) {
    return a.exists == b.exists && a.size == b.size && a.hash == b.hash;
}

static void add_qcc_snapshot_paths(const std::vector<std::string>& inputs,
        std::vector<std::string>& paths) {
    for (const std::string& input : inputs) {
        if (input.empty()) {
            continue;
        }
        if (is_directory(input.c_str())) {
            paths.push_back(input);
            add_module_source_dir(input, paths);
        } else if (is_file(input)) {
            paths.push_back(input);
        }
    }
}

static void capture_qcc_input_snapshots(QCCBuildManifest& manifest,
        const std::string* exact_path = nullptr,
        const QCCFileFingerprint* exact_fingerprint = nullptr) {
    std::vector<std::string> paths;
    add_qcc_snapshot_paths(manifest.inputs, paths);
    add_qcc_snapshot_paths(stub_files, paths);
    add_qcc_snapshot_paths(manifest.extra_inputs, paths);
    if (manifest.include_command_manifest_inputs) {
        add_qcc_snapshot_paths(manifest_inputs, paths);
    }

    std::map<std::string, QCCFileFingerprint> snapshots;
    for (const std::string& path : paths) {
        std::string canonical = canonical_existing_path(path);
        if (snapshots.find(canonical) == snapshots.end()) {
            snapshots.emplace(canonical, qcc_input_fingerprint(canonical));
        }
    }
    if (exact_path && exact_fingerprint) {
        snapshots[canonical_existing_path(*exact_path)] = *exact_fingerprint;
    }
    manifest.input_snapshots = std::make_shared<const std::map<std::string, QCCFileFingerprint>>(
        std::move(snapshots));
}

static bool extend_qcc_input_snapshots(QCCBuildManifest& manifest,
        const std::vector<std::string>& inputs, std::string& error) {
    std::map<std::string, QCCFileFingerprint> snapshots;
    if (manifest.input_snapshots) {
        snapshots = *manifest.input_snapshots;
    }
    std::vector<std::string> paths;
    add_qcc_snapshot_paths(inputs, paths);
    for (size_t i = 0; i < paths.size(); ++i) {
        if (i && !(i % 100)
                && qcc_check_cancel("qcc input snapshot extension")) {
            error = "operation cancelled during qcc input snapshot extension";
            return false;
        }
        const std::string& path = paths[i];
        std::string canonical = canonical_existing_path(path);
        if (snapshots.find(canonical) == snapshots.end()) {
            snapshots.emplace(canonical, qcc_input_fingerprint(canonical));
        }
    }
    manifest.input_snapshots =
        std::make_shared<const std::map<std::string, QCCFileFingerprint>>(
            std::move(snapshots));
    return true;
}

static bool capture_qcc_observed_source_snapshots(QCCBuildManifest& manifest,
        const std::vector<QoreAOTSourceFingerprint>& fingerprints,
        std::string& error) {
    std::map<std::string, QCCFileFingerprint> snapshots;
    size_t i = 0;
    for (const QoreAOTSourceFingerprint& fingerprint : fingerprints) {
        if (i && !(i % 100)
                && qcc_check_cancel("qcc observed source snapshot collection")) {
            error = "operation cancelled during qcc observed source snapshot collection";
            return false;
        }
        snapshots[canonical_existing_path(fingerprint.path)] = {
            true, fingerprint.size, fingerprint.hash};
        ++i;
    }
    manifest.observed_source_snapshots =
        std::make_shared<const std::map<std::string, QCCFileFingerprint>>(
            std::move(snapshots));
    return true;
}

#ifdef QORE_QCC_TEST_HOOKS
//! Returns true if the source a test hook names (in \a source_var) is an input of this qcc, or if it names none
static bool qcc_test_hook_source_matches(const QCCBuildManifest& manifest, const char* source_var) {
    QoreEnvironmentValue source_holder(source_var);
    const char* source = source_holder.c_str();
    if (!source || !*source) {
        return true;
    }
    if (!manifest.input_snapshots) {
        return false;
    }
    std::string canonical_source = canonical_existing_path(source);
    for (const auto& snapshot : *manifest.input_snapshots) {
        if (snapshot.first == canonical_source) {
            return true;
        }
    }
    return false;
}

//! Runs a test hook of qcc: claims \a marker and runs \a command_var's command, then lets qcc continue
/** A test that changes a source while qcc compiles sets the hook's marker and command (and, optionally, the source
    that the qcc it means compiles): the first qcc that reaches the hook creates the marker exclusively
    (O_CREAT|O_EXCL; any other qcc of the build finds it and goes on) and runs the command synchronously (/bin/sh -c),
    so the change happens exactly at that point, with no test process that polls for the marker and no delay for it to
    act in.  The hooks exist only in a qcc built with QORE_QCC_TEST_HOOKS (CMake option of the same name), so that a
    packaged qcc never runs a command taken from its environment.

    @return false with \a error set if the marker cannot be created or the command fails
*/
static bool qcc_run_test_hook(const char* marker, const char* command_var, const char* what, std::string& error) {
    int fd = open(marker, O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC, 0644);
    if (fd < 0) {
        if (errno == EEXIST) {
            // another qcc of the build ran the hook
            return true;
        }
        error = std::string("cannot create qcc ") + what + " test marker '" + marker + "': " + strerror(errno);
        return false;
    }
    if (close(fd) != 0) {
        error = std::string("cannot close qcc ") + what + " test marker '" + marker + "': " + strerror(errno);
        return false;
    }
    QoreEnvironmentValue command_holder(command_var);
    const char* command = command_holder.c_str();
    if (!command || !*command) {
        return true;
    }
    char sh_arg0[] = "sh";
    char sh_arg1[] = "-c";
    std::string command_copy(command);
    char* const argv[] = {sh_arg0, sh_arg1, &command_copy[0], nullptr};
    pid_t pid;
    int rc;
    {
        // the command gets a copy of the environment, which must not change while it is copied; the lock is not held
        // while the command runs
        QoreEnvironmentReadLock env_lock;
        rc = posix_spawn(&pid, "/bin/sh", nullptr, nullptr, argv, environ);
    }
    if (rc) {
        error = std::string("cannot run qcc ") + what + " test command '" + command_copy + "': " + strerror(rc);
        return false;
    }
    int status = 0;
    while (waitpid(pid, &status, 0) < 0) {
        if (errno != EINTR) {
            error = std::string("cannot wait for qcc ") + what + " test command '" + command_copy + "': "
                + strerror(errno);
            return false;
        }
    }
    if (!WIFEXITED(status) || WEXITSTATUS(status)) {
        error = std::string("qcc ") + what + " test command failed (status " + std::to_string(status) + "): "
            + command_copy;
        return false;
    }
    return true;
}
#endif

//! A test hook right after qcc took the snapshot of its inputs (see qcc_run_test_hook())
static bool qcc_test_wait_after_input_snapshot(const QCCBuildManifest& manifest, std::string& error) {
#ifdef QORE_QCC_TEST_HOOKS
    QoreEnvironmentValue marker_holder("QORE_QCC_TEST_AFTER_INPUT_SNAPSHOT_MARKER");
    const char* marker = marker_holder.c_str();
    if (!marker || !*marker || !qcc_test_hook_source_matches(manifest, "QORE_QCC_TEST_AFTER_INPUT_SNAPSHOT_SOURCE")) {
        return true;
    }
    return qcc_run_test_hook(marker, "QORE_QCC_TEST_AFTER_INPUT_SNAPSHOT_COMMAND", "post-snapshot", error);
#else
    return true;
#endif
}

//! A test hook right before qcc validates its inputs against their snapshot (see qcc_run_test_hook())
static bool qcc_test_wait_before_input_validation(const QCCBuildManifest& manifest, std::string& error) {
#ifdef QORE_QCC_TEST_HOOKS
    QoreEnvironmentValue marker_holder("QORE_QCC_TEST_INPUT_VALIDATION_MARKER");
    const char* marker = marker_holder.c_str();
    if (!marker || !*marker || !qcc_test_hook_source_matches(manifest, "QORE_QCC_TEST_INPUT_VALIDATION_SOURCE")) {
        return true;
    }
    return qcc_run_test_hook(marker, "QORE_QCC_TEST_INPUT_VALIDATION_COMMAND", "input-validation", error);
#else
    return true;
#endif
}

enum class QCCFinishResult {
    Success,
    Error,
    InputsChanged,
};

static bool remove_qcc_file_if_exists(const std::string& path,
        std::string& error) {
    if (!unlink(path.c_str()) || errno == ENOENT) {
        return true;
    }
    error = "cannot remove stale qcc success stamp '" + path + "': "
        + strerror(errno);
    return false;
}

static QCCFinishResult validate_qcc_input_snapshots(
        const QCCBuildManifest& manifest, std::string& error) {
    if (!qcc_test_wait_before_input_validation(manifest, error)) {
        return QCCFinishResult::Error;
    }
    if (!manifest.input_snapshots) {
        return QCCFinishResult::Success;
    }
    if (manifest.observed_source_snapshots) {
        size_t i = 0;
        for (const auto& observed : *manifest.observed_source_snapshots) {
            if (i && !(i % 100)
                    && qcc_check_cancel("qcc observed source snapshot validation")) {
                error = "operation cancelled during qcc observed source snapshot validation";
                return QCCFinishResult::Error;
            }
            auto initial = manifest.input_snapshots->find(observed.first);
            if (initial == manifest.input_snapshots->end()
                    || !qcc_file_fingerprint_equal(initial->second, observed.second)) {
                error = "qcc parsed input changed after its initial snapshot while building '"
                    + manifest.output + "'; retry required: '" + observed.first + "'";
                return QCCFinishResult::InputsChanged;
            }
            ++i;
        }
    }
    size_t i = 0;
    for (const auto& snapshot : *manifest.input_snapshots) {
        if (i && !(i % 100)
                && qcc_check_cancel("qcc build input snapshot validation")) {
            error = "operation cancelled during qcc build input snapshot validation";
            return QCCFinishResult::Error;
        }
        QCCFileFingerprint current = qcc_input_fingerprint(snapshot.first);
        if (!qcc_file_fingerprint_equal(snapshot.second, current)) {
            error = "qcc input changed while building '" + manifest.output
                + "'; retry required: '" + snapshot.first + "'";
            return QCCFinishResult::InputsChanged;
        }
        ++i;
    }
    return QCCFinishResult::Success;
}

static std::string qcc_fingerprint_hash_string(const QCCFileFingerprint& fp) {
    return fp.exists ? "xxh64:" + hex64_string(fp.hash) : "";
}

static bool touch_qcc_file(const char* path, std::string& error) {
    if (!path || !*path) {
        return true;
    }

    FILE* f = fopen(path, "ab");
    if (!f) {
        error = "cannot open stamp '" + std::string(path) + "': " + strerror(errno);
        return false;
    }
    if (fclose(f) != 0) {
        error = "cannot close stamp '" + std::string(path) + "': " + strerror(errno);
        return false;
    }
    if (utime(path, nullptr) != 0) {
        error = "cannot touch stamp '" + std::string(path) + "': " + strerror(errno);
        return false;
    }
    return true;
}

static bool write_qcc_status_json_file(const QCCBuildManifest& manifest,
        bool built, bool skipped, bool output_changed,
        const QCCFileFingerprint& output_fp, std::string& error) {
    if (!write_status_json_path) {
        return true;
    }

    char* buf = nullptr;
    size_t size = 0;
    FILE* f = open_memstream(&buf, &size);
    if (!f) {
        error = "cannot allocate qcc status JSON buffer: " + std::string(strerror(errno));
        return false;
    }

    fputs("{\n", f);
    write_json_file_u64_field(f, "format", 1, 2);
    write_json_file_string_field(f, "tool", "qcc", 2);
    write_json_file_string_field(f, "kind", manifest.kind, 2);
    write_json_file_string_field(f, "output", manifest.output, 2);
    write_json_file_bool_field(f, "built", built, 2);
    write_json_file_bool_field(f, "skipped", skipped, 2);
    write_json_file_bool_field(f, "manifest_current", skipped, 2);
    write_json_file_bool_field(f, "output_changed", output_changed, 2);
    write_json_file_u64_field(f, "output_size", output_fp.size, 2);
    write_json_file_string_field(f, "output_hash", qcc_fingerprint_hash_string(output_fp), 2);
    fprintf(f, "  \"sidecars\": {\n");
    write_json_file_string_field(f, "status_json", write_status_json_path ? write_status_json_path : "", 4);
    write_json_file_string_field(f, "index_json", manifest.index_json, 4);
    write_json_file_string_field(f, "manifest", write_manifest_path ? write_manifest_path : "", 4);
    write_json_file_string_field(f, "depfile", manifest.depfile, 4);
    write_json_file_string_field(f, "link_map", manifest.link_map, 4);
    write_json_file_string_field(f, "success_stamp", success_stamp_path ? success_stamp_path : "", 4);
    write_json_file_string_field(f, "content_stamp", content_stamp_path ? content_stamp_path : "", 4);
    write_json_file_string_field(f, "compile_contract_stamp",
        compile_contract_stamp_path ? compile_contract_stamp_path : "", 4);
    write_json_file_string_field(f, "aggregate_contract_stamp",
        aggregate_contract_stamp_path ? aggregate_contract_stamp_path : "", 4, "");
    fputs("  }\n", f);
    fputs("}\n", f);

    bool ok = true;
    if (fclose(f) != 0) {
        error = "cannot close qcc status JSON buffer: " + std::string(strerror(errno));
        ok = false;
    }
    std::string content;
    if (ok) {
        content.assign(buf, size);
    }
    free(buf);
    return ok && write_generated_file_if_changed(write_status_json_path, content, error);
}

static bool build_qcc_manifest_content(const QCCBuildManifest& manifest,
        const char* argv0, std::string& content, std::string& error,
        bool use_input_snapshots = false) {
    if (manifest.output.empty() || !is_file(manifest.output)) {
        return false;
    }

    char* buf = nullptr;
    size_t size = 0;
    FILE* f = open_memstream(&buf, &size);
    if (!f) {
        error = "cannot allocate qcc manifest buffer: " + std::string(strerror(errno));
        return false;
    }

    fputs("{\n", f);
    write_json_file_u64_field(f, "format", 1, 2);
    write_json_file_string_field(f, "tool", "qcc", 2);
    write_json_file_string_field(f, "manifest_version", "2026-06-14-qcc-build-v1", 2);
    write_json_file_string_field(f, "kind", manifest.kind, 2);
    std::string qcc_path = resolve_command_path(argv0);
    if (is_file(qcc_path)) {
        if (!write_json_file_record(f, "qcc", qcc_path, 2, error)) {
            fclose(f);
            free(buf);
            return false;
        }
    } else {
        write_json_file_string_field(f, "qcc", qcc_path, 2);
    }
    if (!write_json_file_record(f, "output", manifest.output, 2, error)) {
        fclose(f);
        free(buf);
        return false;
    }

    fprintf(f, "  \"sidecars\": {\n");
    write_json_file_string_field(f, "index_json", manifest.index_json, 4);
    write_json_file_string_field(f, "depfile", manifest.depfile, 4);
    write_json_file_string_field(f, "link_map", manifest.link_map, 4);
    write_json_file_string_field(f, "compile_contract_stamp",
        compile_contract_stamp_path ? compile_contract_stamp_path : "", 4);
    write_json_file_string_field(f, "aggregate_contract_stamp",
        aggregate_contract_stamp_path ? aggregate_contract_stamp_path : "", 4, "");
    fputs("  },\n", f);

    fprintf(f, "  \"options\": {\n");
    write_json_file_u64_field(f, "opt_level", opt_level, 4);
    write_json_file_string_field(f, "target_triple", target_triple ? target_triple : "", 4);
    write_json_file_bool_field(f, "include_source", include_source, 4);
    write_json_file_bool_field(f, "strip_debug_info", strip_debug_info, 4);
    write_json_file_bool_field(f, "warnings_are_errors", warnings_are_errors, 4);
    write_json_file_bool_field(f, "allow_unresolved_imports", allow_unresolved_qo_imports, 4);
    write_json_file_bool_field(f, "strict_call_relocations", strict_call_relocations, 4);
    write_json_file_bool_field(f, "script_aggregate_native_registers",
        script_aggregate_native_registers, 4);
    write_json_file_bool_field(f, "depfile_qo_input_content_stamps",
        depfile_qo_input_content_stamps, 4);
    write_json_file_bool_field(f, "depfile_compile_contract_stamps",
        depfile_compile_contract_stamps, 4);
    write_json_file_bool_field(f, "depfile_declaration_contract_stamps",
        depfile_declaration_contract_stamps, 4);
    write_json_file_string_field(f, "depfile_module_deps",
        depfile_module_deps_mode_name(), 4);
    write_json_file_string_field(f, "aggregate_symbol", manifest.aggregate_symbol, 4, "");
    fputs("  },\n", f);

    std::vector<std::string> manifest_prefix_maps;
    for (size_t i = 0; i < file_prefix_maps.size(); ++i) {
        if (i && !(i % 100) && qcc_check_cancel("qcc source-prefix map manifest")) {
            error = "operation cancelled during source-prefix map manifest generation";
            fclose(f);
            free(buf);
            return false;
        }
        manifest_prefix_maps.push_back(file_prefix_maps[i].first + "=" + file_prefix_maps[i].second);
    }
    if (!json_file_string_array(f, "file_prefix_maps", manifest_prefix_maps, error)) {
        fclose(f);
        free(buf);
        return false;
    }

    fprintf(f, "  \"environment\": {\n");
    QoreEnvironmentValue qore_include_dir_holder("QORE_INCLUDE_DIR");
    const char* qore_include_dir = qore_include_dir_holder.c_str();
    QoreEnvironmentValue qore_module_dir_holder("QORE_MODULE_DIR");
    const char* qore_module_dir = qore_module_dir_holder.c_str();
    QoreEnvironmentValue qore_big_fn_threshold_holder("QORE_AOT_BIG_FN_THRESHOLD");
    const char* qore_big_fn_threshold = qore_big_fn_threshold_holder.c_str();
    QoreEnvironmentValue qore_metadata_compression_holder("QORE_AOT_METADATA_COMPRESSION");
    const char* qore_metadata_compression = qore_metadata_compression_holder.c_str();
    write_json_file_string_field(f, "QORE_INCLUDE_DIR", qore_include_dir ? qore_include_dir : "", 4);
    write_json_file_string_field(f, "QORE_MODULE_DIR", qore_module_dir ? qore_module_dir : "", 4);
    write_json_file_string_field(f, "QORE_AOT_BIG_FN_THRESHOLD",
        qore_big_fn_threshold ? qore_big_fn_threshold : "", 4);
    write_json_file_string_field(f, "QORE_AOT_METADATA_COMPRESSION",
        qore_metadata_compression ? qore_metadata_compression : "", 4, "");
    fputs("  },\n", f);

    std::vector<std::string> all_inputs = manifest.inputs;
    for (const std::string& stub : stub_files) {
        all_inputs.push_back(stub);
    }
    all_inputs.insert(all_inputs.end(), manifest.extra_inputs.begin(), manifest.extra_inputs.end());
    if (manifest.include_command_manifest_inputs) {
        all_inputs.insert(all_inputs.end(), manifest_inputs.begin(), manifest_inputs.end());
    }
    if (!manifest.depfile.empty() && is_file(manifest.depfile)) {
        all_inputs.push_back(manifest.depfile);
        read_make_depfile_inputs(manifest.depfile, all_inputs);
    }
    if (!manifest.link_map.empty() && is_file(manifest.link_map)) {
        all_inputs.push_back(manifest.link_map);
    }
    if (!manifest.index_json.empty() && is_file(manifest.index_json)) {
        all_inputs.push_back(manifest.index_json);
    }
    if (!write_json_file_record_array(f, "inputs", all_inputs, 2, error, ",",
            use_input_snapshots && manifest.input_snapshots
                ? manifest.input_snapshots.get() : nullptr)) {
        fclose(f);
        free(buf);
        return false;
    }

    fprintf(f, "  \"parse_defines\": [");
    for (size_t i = 0; i < parse_defines.size(); ++i) {
        if (i) {
            fputs(", ", f);
        }
        json_file_string(f, parse_defines[i]);
    }
    fputs("],\n", f);
    fprintf(f, "  \"parse_options\": [");
    for (size_t i = 0; i < parse_option_flags.size(); ++i) {
        if (i) {
            fputs(", ", f);
        }
        json_file_string(f, parse_option_flags[i]);
    }
    fputs("],\n", f);
    fprintf(f, "  \"load_modules\": [");
    for (size_t i = 0; i < load_modules.size(); ++i) {
        if (i) {
            fputs(", ", f);
        }
        json_file_string(f, load_modules[i]);
    }
    fputs("]\n", f);
    fputs("}\n", f);

    if (fclose(f) != 0) {
        error = "cannot close qcc manifest buffer: " + std::string(strerror(errno));
        free(buf);
        return false;
    }
    content.assign(buf, size);
    free(buf);
    return true;
}

static bool qcc_manifest_current(const QCCBuildManifest& manifest, const char* argv0) {
    if (!write_manifest_path || !is_file(write_manifest_path)) {
        return false;
    }
    std::string expected;
    std::string error;
    if (!build_qcc_manifest_content(manifest, argv0, expected, error, true)) {
        return false;
    }
    std::string old;
    return read_file(write_manifest_path, old) && old == expected;
}

static bool write_qcc_manifest_file(const QCCBuildManifest& manifest,
        const char* argv0, std::string& error) {
    if (!write_manifest_path) {
        return true;
    }
    std::string content;
    if (!build_qcc_manifest_content(manifest, argv0, content, error, true)) {
        if (error.empty()) {
            error = "cannot build qcc manifest for '" + manifest.output + "'";
        }
        return false;
    }
    return write_generated_file_if_changed(write_manifest_path, content, error);
}

static bool write_requested_sidecars(const QCCBuildManifest& manifest,
        const char* argv0, bool allow_empty_index, std::string& error) {
    if (write_index_json_path) {
        if (!write_aot_index_json_file(write_index_json_path,
                manifest.output.c_str(), allow_empty_index, error,
                compile_contract_stamp_path,
                aggregate_contract_stamp_path)) {
            return false;
        }
    } else {
        if (compile_contract_stamp_path
                && !write_aot_compile_contract_stamp_file(
                    compile_contract_stamp_path, manifest.output.c_str(), error)) {
            return false;
        }
        if (aggregate_contract_stamp_path
                && !write_aot_aggregate_contract_stamp_file(
                    aggregate_contract_stamp_path, manifest.output.c_str(), error)) {
            return false;
        }
    }
    // Not folded into write_aot_index_json_file() with the other two: that call
    // writes the contracts it also embeds in the index, and the body contract is a
    // separate sidecar rather than an index field.
    if (body_contract_stamp_path
            && !write_aot_body_contract_stamp_file(
                body_contract_stamp_path, manifest.output.c_str(), error)) {
        return false;
    }
    if (declaration_contract_stamp_path
            && !write_aot_declaration_contract_stamp_file(
                declaration_contract_stamp_path, manifest.output.c_str(), error)) {
        return false;
    }
    return write_qcc_manifest_file(manifest, argv0, error);
}

static QCCFinishResult finish_qcc_build(const QCCBuildManifest& manifest, const char* argv0,
        const QCCFileFingerprint& before, bool built, bool skipped,
        bool allow_empty_index, std::string& error, bool validate_inputs = true) {
    QCCFinishResult input_result = QCCFinishResult::Success;
    if (validate_inputs) {
        input_result = validate_qcc_input_snapshots(manifest, error);
        if (input_result != QCCFinishResult::Success) {
            return input_result;
        }
    }
    if (built && !write_requested_sidecars(manifest, argv0, allow_empty_index, error)) {
        return QCCFinishResult::Error;
    }
    if (skipped && compile_contract_stamp_path
            && !is_file(compile_contract_stamp_path)
            && !write_aot_compile_contract_stamp_file(
                compile_contract_stamp_path, manifest.output.c_str(), error)) {
        return QCCFinishResult::Error;
    }
    if (skipped && aggregate_contract_stamp_path
            && !is_file(aggregate_contract_stamp_path)
            && !write_aot_aggregate_contract_stamp_file(
                aggregate_contract_stamp_path, manifest.output.c_str(), error)) {
        return QCCFinishResult::Error;
    }
    if (skipped && declaration_contract_stamp_path
            && !is_file(declaration_contract_stamp_path)
            && !write_aot_declaration_contract_stamp_file(
                declaration_contract_stamp_path, manifest.output.c_str(), error)) {
        return QCCFinishResult::Error;
    }
    if (skipped && body_contract_stamp_path
            && !is_file(body_contract_stamp_path)
            && !write_aot_body_contract_stamp_file(
                body_contract_stamp_path, manifest.output.c_str(), error)) {
        return QCCFinishResult::Error;
    }
    QCCFileFingerprint after = qcc_file_fingerprint(manifest.output);
    if (!after.exists) {
        error = "generated output missing after successful qcc command: '" + manifest.output + "'";
        return QCCFinishResult::Error;
    }

    bool output_changed = built && !qcc_file_fingerprint_equal(before, after);
    if (!write_qcc_status_json_file(manifest, built, skipped, output_changed, after, error)) {
        return QCCFinishResult::Error;
    }
    bool content_stamp_missing = content_stamp_path && !is_file(content_stamp_path);
    if (content_stamp_path && (output_changed || ((built || skipped) && content_stamp_missing))
            && !touch_qcc_file(content_stamp_path, error)) {
        return QCCFinishResult::Error;
    }
    if (success_stamp_path && !touch_qcc_file(success_stamp_path, error)) {
        return QCCFinishResult::Error;
    }
    if (validate_inputs) {
        input_result = validate_qcc_input_snapshots(manifest, error);
        if (input_result != QCCFinishResult::Success) {
            if (success_stamp_path) {
                std::string cleanup_error;
                if (!remove_qcc_file_if_exists(success_stamp_path,
                        cleanup_error)) {
                    error += "; additionally, " + cleanup_error;
                    return QCCFinishResult::Error;
                }
            }
            return input_result;
        }
    }
    return QCCFinishResult::Success;
}

static int qcc_finish_error_exit(QCCFinishResult result) {
    return result == QCCFinishResult::InputsChanged ? 75 : 1;
}

static bool qcc_single_output_sidecars_requested() {
    return write_index_json_path || write_manifest_path || skip_if_manifest_current
        || write_status_json_path || success_stamp_path || content_stamp_path
        || compile_contract_stamp_path || aggregate_contract_stamp_path;
}

static void add_existing_qo_inputs_from_args(std::vector<std::string>& inputs,
        int begin, int argc, char** argv) {
    for (int i = begin; i < argc; ++i) {
        inputs.push_back(canonical_existing_path(argv[i]));
    }
}

//! Prints the AOT module metadata that qcc stores in a section of a qmod's image
/** The loader reads the same metadata before it maps the module; see QoreAOTModuleFileInfo.
*/
static void print_aot_module_info(const char* path) {
    QoreAOTModuleFileInfo info;
    QoreAOTModuleInfoLocation location;
    std::string error;
    switch (qoreAOTReadModuleInfo(path, info, error, &location)) {
        case QoreAOTModuleInfoStatus::NONE:
            printf("  AOT module metadata: none found\n");
            return;
        case QoreAOTModuleInfoStatus::INVALID:
            printf("  AOT module metadata: invalid: %s\n", error.c_str());
            return;
        case QoreAOTModuleInfoStatus::FOUND:
            break;
    }
    printf("  AOT module metadata: %s, offset 0x%llx, %llu bytes\n", location.container.c_str(),
        static_cast<unsigned long long>(location.offset), static_cast<unsigned long long>(location.size));
    printf("    module: %s\n", info.module_name.c_str());
    printf("    dependencies: %zu\n", info.dependencies.size());
    for (size_t i = 0; i < info.dependencies.size(); ++i) {
        if (!dump_aot_symbol_index_check_cancel(i, "AOT module metadata dump")) {
            return;
        }
        printf("      %s\n", info.dependencies[i].c_str());
    }
    printf("    unavailable optional modules: %zu\n", info.unavailable_optional_modules.size());
    for (size_t i = 0; i < info.unavailable_optional_modules.size(); ++i) {
        if (!dump_aot_symbol_index_check_cancel(i, "AOT module metadata dump")) {
            return;
        }
        printf("      %s\n", info.unavailable_optional_modules[i].c_str());
    }
    printf("    compiled with: %zu\n", info.compiled_with.size());
    for (size_t i = 0; i < info.compiled_with.size(); ++i) {
        if (!dump_aot_symbol_index_check_cancel(i, "AOT module metadata dump")) {
            return;
        }
        printf("      %s\n", info.compiled_with[i].c_str());
    }
    printf("    prepended module paths: %zu\n", info.prepended_module_paths.size());
    for (const std::string& dir : info.prepended_module_paths) {
        printf("      %s\n", dir.c_str());
    }
    printf("    appended module paths: %zu\n", info.appended_module_paths.size());
    for (const std::string& dir : info.appended_module_paths) {
        printf("      %s\n", dir.c_str());
    }
}

static int dump_aot_info_for_file(const char* path) {
    printf("%s:\n", path);

    std::vector<AOTDumpMetadataBlob> blobs;
    std::set<std::string> seen;
    inspect_object_file(path, blobs, seen);

    std::string contents;
    if (!read_file(path, contents)) {
        return 1;
    }
    scan_aot_metadata_blobs(contents, blobs, seen);

    if (blobs.empty()) {
        printf("  AOT metadata: none found\n");
    } else {
        for (size_t i = 0; i < blobs.size(); ++i) {
            dump_aot_metadata_blob(blobs[i], i + 1);
        }
    }
    print_aot_module_info(path);

    return 0;
}

static std::string get_default_output(const char* input_path, bool is_module,
        bool compile_only_mode = false) {
    std::string output = input_path;

    // Strip directory path for basename
    size_t slash = output.rfind('/');
    if (slash != std::string::npos) {
        output = output.substr(slash + 1);
    }

    // Strip extension
    size_t dot = output.rfind('.');
    if (dot != std::string::npos && dot > 0) {
        output = output.substr(0, dot);
    }

    // -c emits a relocatable .qo regardless of source kind
    if (compile_only_mode) {
        output += ".qo";
    } else if (is_module) {
        output += ".qmod";
    }

    return output;
}

//! Create a private temporary directory for qcc-generated objects.
static bool make_qcc_temp_dir(std::string& temp_dir, std::string& error) {
    QoreEnvironmentValue base_holder("TMPDIR");
    const char* base = base_holder.c_str();
    if (!base || !*base) {
        base = "/tmp";
    }
    std::string tmpl = join_path(base, "qcc-aot-XXXXXX");
    std::vector<char> buf(tmpl.begin(), tmpl.end());
    buf.push_back('\0');
    char* path = mkdtemp(buf.data());
    if (!path) {
        error = std::string("cannot create temporary directory from '")
            + tmpl + "': " + strerror(errno);
        return false;
    }
    temp_dir = path;
    return true;
}

//! Remove regular temporary files generated under @p temp_dir.
static void cleanup_qcc_temp_dir(const std::string& temp_dir) {
    DIR* d = opendir(temp_dir.c_str());
    if (d) {
        struct dirent* ent;
        while ((ent = readdir(d)) != nullptr) {
            if (!strcmp(ent->d_name, ".") || !strcmp(ent->d_name, "..")) {
                continue;
            }
            std::string path = join_path(temp_dir, ent->d_name);
            unlink(path.c_str());
        }
        closedir(d);
    }
    rmdir(temp_dir.c_str());
}

//! Mirror QoreAOT.cpp's scriptBatchSourceId() for batch `.qo` output names.
static bool get_batch_object_path(const std::string& source_path,
        const std::string& output_dir, std::string& object_path,
        std::string& error) {
    char* resolved = realpath(source_path.c_str(), nullptr);
    if (!resolved) {
        error = "cannot resolve source file '" + source_path + "': "
            + strerror(errno);
        return false;
    }
    std::string canon = resolved;
    free(resolved);
    object_path = output_dir + "/" + sanitize_c_identifier(canon) + ".qo";
    return true;
}

struct AOTCompileContractProviderMap {
    std::map<std::string, std::string> stamps;
    std::set<std::string> ambiguous_sources;
};

static bool build_aot_compile_contract_provider_map(
        const std::vector<std::string>& provider_objects,
        AOTCompileContractProviderMap& providers, std::string& error) {
    for (size_t i = 0; i < provider_objects.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT compile-contract provider scan", error)) {
            return false;
        }
        const std::string stamp_path = provider_objects[i]
            + ".compile-contract.stamp";
        if (!is_file(stamp_path)) {
            continue;
        }
        const std::string stamp = canonical_existing_path(stamp_path);
        QOLinkInputInfo provider;
        if (!collect_qo_link_input(provider_objects[i].c_str(),
                provider, error)) {
            return false;
        }
        std::set<std::string> object_sources;
        for (size_t j = 0; j < provider.index.defined.size(); ++j) {
            if (!qo_link_check_cancel(j,
                    "AOT compile-contract provider definition scan", error)) {
                return false;
            }
            const std::string& source = provider.index.defined[j].source_file;
            if (source.empty() || source.front() == '<') {
                continue;
            }
            std::string canon = canonical_existing_path(source);
            object_sources.insert(std::move(canon));
        }
        size_t source_i = 0;
        for (const std::string& source : object_sources) {
            if (!qo_link_check_cancel(source_i++,
                    "AOT compile-contract provider source mapping", error)) {
                return false;
            }
            auto [found, inserted] = providers.stamps.emplace(source, stamp);
            if (!inserted && found->second != stamp) {
                providers.ambiguous_sources.insert(source);
            }
        }
    }
    return true;
}

//! Adds the provider source of every hash-verified import to a script object's depfile.
/** `--link-qo` validates each imported symbol's recorded signature/declaration/value/body-contract
    hash against the hash the providing object publishes, so an import whose record carries any of
    those hashes is a hard build dependency: if the provider's declaration changes, this object's
    recorded hash goes stale and the aggregate link fails with "qo-link hash mismatch" naming a
    consumer the build had no reason to rebuild.

    The parse-time dependency sink only records declarations whose VALUES the target folds
    (constants, enum members), on the assumption that every other cross-unit reference re-resolves by
    name at load time.  That holds for the runtime, but not for these link-time hash checks — the
    consumer object bakes the provider's hash in.  Recording the provider source closes that hole; a
    following `--depfile-compile-contract-stamps` pass narrows each entry to the provider's
    compile-contract stamp so unrelated provider edits still do not rebuild this object.

    A provider source this object also defines into is skipped: an object cannot depend on itself.

    @param object_path the generated `.qo` whose symbol index names the providers
    @param depfile the Make-format dependency file to extend; a missing file is a no-op
    @param depfile_target the target written before the colon when the file is rewritten
    @param error receives a description when the depfile cannot be read back or rewritten

    @return true on success, false with @a error set on failure */
static bool add_aot_import_provider_depfile_inputs(
        const std::string& object_path, const std::string& depfile,
        const std::string& depfile_target, std::string& error) {
    if (depfile.empty() || !is_file(depfile)) {
        return true;
    }

    QOLinkInputInfo consumer;
    if (!collect_qo_link_input(object_path.c_str(), consumer, error)) {
        return false;
    }

    std::set<std::string> owned_sources;
    for (size_t i = 0; i < consumer.index.defined.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT import-provider owned-source collection", error)) {
            return false;
        }
        const std::string& source = consumer.index.defined[i].source_file;
        if (!source.empty() && source.front() != '<') {
            owned_sources.insert(canonical_existing_path(source));
        }
    }

    std::set<std::string> provider_sources;
    for (size_t i = 0; i < consumer.index.imported.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT import-provider dependency collection", error)) {
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = consumer.index.imported[i];
        // only hash-verified imports need the edge: an import with no recorded hash is resolved by
        // name at load time and cannot go stale
        if (rec.signature_hash.empty() && rec.declaration_hash.empty()
                && rec.value_hash.empty() && rec.body_contract_hash.empty()) {
            continue;
        }
        const std::string& provider = rec.provider_source_file;
        if (provider.empty() || provider.front() == '<') {
            continue;
        }
        std::string canon = canonical_existing_path(provider);
        if (!owned_sources.count(canon)) {
            provider_sources.insert(std::move(canon));
        }
    }
    if (provider_sources.empty()) {
        return true;
    }

    std::vector<std::string> deps;
    read_make_depfile_inputs(depfile, deps);
    std::set<std::string> present;
    for (size_t i = 0; i < deps.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT import-provider depfile scan", error)) {
            return false;
        }
        present.insert(canonical_existing_path(deps[i]));
    }
    bool changed = false;
    size_t provider_i = 0;
    for (const std::string& provider : provider_sources) {
        if (!qo_link_check_cancel(provider_i++,
                "AOT import-provider depfile merge", error)) {
            return false;
        }
        if (present.insert(provider).second) {
            deps.push_back(provider);
            changed = true;
        }
    }
    if (!changed) {
        return true;
    }
    std::sort(deps.begin(), deps.end());
    if (!write_depfile_list(depfile.c_str(), depfile_target, deps)) {
        error = "cannot add AOT import providers to depfile '" + depfile + "'";
        return false;
    }
    return true;
}

static bool rewrite_aot_compile_contract_depfile(
        const std::string& object_path,
        const std::vector<std::string>& library_dirs,
        const std::string& depfile, const std::string& depfile_target,
        std::string& error,
        const AOTCompileContractProviderMap* known_providers = nullptr) {
    if (!depfile_compile_contract_stamps || depfile.empty()
            || !is_file(depfile)) {
        return true;
    }

    QOLinkInputInfo consumer;
    if (!collect_qo_link_input(object_path.c_str(), consumer, error)) {
        return false;
    }
    std::set<std::string> imported_sources;
    for (size_t i = 0; i < consumer.index.imported.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT compile-contract import collection", error)) {
            return false;
        }
        const std::string& provider =
            consumer.index.imported[i].provider_source_file;
        if (!provider.empty() && provider.front() != '<') {
            imported_sources.insert(canonical_existing_path(provider));
        }
    }
    if (imported_sources.empty()) {
        return true;
    }

    std::set<std::string> owned_sources;
    for (size_t i = 0; i < consumer.index.defined.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT compile-contract owned-source collection", error)) {
            return false;
        }
        const std::string& source = consumer.index.defined[i].source_file;
        if (!source.empty() && source.front() != '<') {
            owned_sources.insert(canonical_existing_path(source));
        }
    }

    AOTCompileContractProviderMap local_providers;
    if (!known_providers) {
        std::vector<std::string> provider_objects;
        collect_qo_library_inputs(provider_objects, library_dirs, object_path);
        if (!build_aot_compile_contract_provider_map(provider_objects,
                local_providers, error)) {
            return false;
        }
        known_providers = &local_providers;
    }

    std::vector<std::string> deps;
    read_make_depfile_inputs(depfile, deps);
    for (size_t i = 0; i < deps.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT compile-contract depfile rewrite", error)) {
            return false;
        }
        std::string canon = canonical_existing_path(deps[i]);
        auto stamp = known_providers->stamps.find(canon);
        if (imported_sources.count(canon)
                && stamp != known_providers->stamps.end()
                && !owned_sources.count(canon)
                && !known_providers->ambiguous_sources.count(canon)) {
            deps[i] = stamp->second;
        }
    }
    if (!write_depfile_list(depfile.c_str(), depfile_target, deps)) {
        error = "cannot rewrite AOT compile-contract depfile '" + depfile
            + "'";
        return false;
    }
    return true;
}

//! Narrows a folded-value source dependency to the provider's DECLARATION contract.
/** The parse-time dependency sink records a provider's SOURCE for the references that leave
    nothing behind in the emitted object: a folded compile-time constant (ConstantList) and a
    class type resolved during a batch parse.  Neither produces an import record, so
    rewrite_aot_compile_contract_depfile() cannot narrow them and they fall through to
    rewrite_depfile_source_content_stamps(), which records the provider's source-content digest.

    That dependency is genuinely required -- a folded value leaves no trace, so nothing else would
    rebuild this object when the value changes -- but SOURCE-BYTE granularity is wrong for it:
    appending a comment to a provider rebuilds every object that folded any constant from it, and
    the consumer closure of a widely included source is most of the group.  The provider's
    declaration contract (`.declaration-contract.stamp`) is the content-preserving description of
    exactly what such a reference consumes: build_aot_declaration_contract_content() carries a
    value_hash for every constant the provider defines and a signature/declaration hash for every
    type it declares, and omits the lowering artifacts -- native rows, body contracts, the feature
    bitset -- that make the same source's COMPILE contract differ between a whole-group parse and a
    standalone one, and the rows only the script aggregate depends on (declaration locations,
    embedded default values), which the provider's `.aggregate-contract.stamp` adds.

    Two classes of dependency are deliberately left alone:

    - a source this object also defines into: an object cannot depend on itself, and its own
      source bytes are what must rebuild it; and
    - a source this object imports with a recorded body-contract hash.  `--link-qo` validates that
      hash against the provider, and a body contract is not part of a declaration contract, so
      such a consumer must still be rebuilt when the provider's BODY moves.  Those are already
      narrowed to the provider's compile-contract stamp by the pass before this one, which does
      carry the body-contract hash; excluding them here keeps this pass from widening what that
      pass deliberately narrowed.

    The one reference class this cannot distinguish is the transitive body provenance that a batch
    fast-call records through qore_aot_note_dependency_file(): the file whose body was inlined
    leaves no import record of its own.  Instrumenting the four dependency feeders over a
    whole-group parse of an 875-source group recorded 3921 edges from the two folded-constant
    sites and 0 from either body-contract site, so the class is empty in practice; a build that
    needs it can leave --depfile-declaration-contract-stamps off.

    @param object_path the generated `.qo` whose symbol index names what it owns and imports
    @param library_dirs where to look for provider objects when @a known_providers is not given
    @param depfile the Make-format dependency file to rewrite; a missing file is a no-op
    @param depfile_target the target written before the colon when the file is rewritten
    @param error receives a description when the depfile cannot be read back or rewritten
    @param known_providers a source -> compile-contract-stamp map already built by the caller

    @return true on success, false with @a error set on failure */
static bool rewrite_aot_declaration_contract_depfile(
        const std::string& object_path,
        const std::vector<std::string>& library_dirs,
        const std::string& depfile, const std::string& depfile_target,
        std::string& error,
        const AOTCompileContractProviderMap* known_providers = nullptr) {
    if (!depfile_declaration_contract_stamps || depfile.empty()
            || depfile_source_content_stamps.empty() || !is_file(depfile)) {
        return true;
    }

    QOLinkInputInfo consumer;
    if (!collect_qo_link_input(object_path.c_str(), consumer, error)) {
        return false;
    }

    std::set<std::string> excluded_sources;
    for (size_t i = 0; i < consumer.index.defined.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT declaration-contract owned-source collection", error)) {
            return false;
        }
        const std::string& source = consumer.index.defined[i].source_file;
        if (!source.empty() && source.front() != '<') {
            excluded_sources.insert(canonical_existing_path(source));
        }
    }
    for (size_t i = 0; i < consumer.index.imported.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT declaration-contract body-import collection", error)) {
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = consumer.index.imported[i];
        if (rec.body_contract_hash.empty()) {
            continue;
        }
        const std::string& provider = rec.provider_source_file;
        if (!provider.empty() && provider.front() != '<') {
            excluded_sources.insert(canonical_existing_path(provider));
        }
    }

    AOTCompileContractProviderMap local_providers;
    if (!known_providers) {
        std::vector<std::string> provider_objects;
        collect_qo_library_inputs(provider_objects, library_dirs, object_path);
        if (!build_aot_compile_contract_provider_map(provider_objects,
                local_providers, error)) {
            return false;
        }
        known_providers = &local_providers;
    }

    static const std::string compile_suffix = ".compile-contract.stamp";
    static const std::string declaration_suffix = ".declaration-contract.stamp";

    std::vector<std::string> deps;
    read_make_depfile_inputs(depfile, deps);
    bool changed = false;
    for (size_t i = 0; i < deps.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT declaration-contract depfile rewrite", error)) {
            return false;
        }
        const std::string canon = canonical_existing_path(deps[i]);
        // Only a member of this build group can be narrowed: the source-content map is the
        // group's own list of its sources, and a provider outside it publishes no contract here.
        if (!depfile_source_content_stamps.count(canon)
                || excluded_sources.count(canon)
                || known_providers->ambiguous_sources.count(canon)) {
            continue;
        }
        auto stamp = known_providers->stamps.find(canon);
        if (stamp == known_providers->stamps.end()) {
            continue;
        }
        const std::string& compile_stamp = stamp->second;
        if (compile_stamp.size() <= compile_suffix.size()
                || compile_stamp.compare(compile_stamp.size() - compile_suffix.size(),
                    compile_suffix.size(), compile_suffix)) {
            continue;
        }
        std::string declaration_stamp =
            compile_stamp.substr(0, compile_stamp.size() - compile_suffix.size())
            + declaration_suffix;
        if (!is_file(declaration_stamp)) {
            continue;
        }
        deps[i] = std::move(declaration_stamp);
        changed = true;
    }
    if (!changed) {
        return true;
    }
    std::sort(deps.begin(), deps.end());
    deps.erase(std::unique(deps.begin(), deps.end()), deps.end());
    if (!write_depfile_list(depfile.c_str(), depfile_target, deps)) {
        error = "cannot rewrite AOT declaration-contract depfile '" + depfile + "'";
        return false;
    }
    return true;
}

//! Suffix of the sidecar naming the body-contract rows an object baked, beside the object itself
static const char AOTBodyContractImportsSuffix[] = ".body-contract-imports";

//! Removes an object's body-contract imports sidecar; a missing file is not an error
static bool remove_aot_body_contract_imports(const std::string& path, std::string& error) {
    if (!unlink(path.c_str()) || errno == ENOENT) {
        return true;
    }
    error = "cannot remove stale body-contract imports '" + path + "': " + strerror(errno);
    return false;
}

//! Writes the body-contract rows an object baked, one `import` row per (provider stamp, symbol)
/** Format 1, one row per line after the header, each field length-prefixed as in the
    contracts themselves -- symbol paths can contain any byte, a newline included:

        import\t<n>:<provider .qo.body-contract.stamp path><n>:<qore path>

    The provider stamp is spelled exactly as the depfile spells it, which is how the
    scheduler pairs the two.  A row names a symbol, not a hash: the scheduler digests the
    provider's CURRENT rows for these symbols, so a consumer is stale exactly when one of
    them moved, and a symbol the provider no longer publishes a body contract for counts
    as moved.

    Written only if the content changed, and removed when there is nothing to record.
*/
static bool write_aot_body_contract_imports(const std::string& path, std::vector<std::string>& rows,
        std::string& error) {
    if (rows.empty()) {
        return remove_aot_body_contract_imports(path, error);
    }
    std::sort(rows.begin(), rows.end());
    rows.erase(std::unique(rows.begin(), rows.end()), rows.end());
    std::string content = "format=1\n";
    for (size_t i = 0; i < rows.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT body-contract import serialization", error)) {
            return false;
        }
        content += rows[i];
        content.push_back('\n');
    }
    return write_generated_file_if_changed(path, content, error);
}

//! Records the body contract of every provider whose body hash this object baked.
/** The scheduler's generation token watches a predecessor's DECLARATION contract,
    which carries no body-contract hashes -- that is what makes it identical between
    a whole-group parse and a standalone one, and what removed the cascade.  It also
    means the token cannot see a provider's body contract move, and `--link-qo`
    compares exactly that: a consumer that recorded a provider's body hash and was
    not rebuilt when it changed fails the aggregate link with "qo-link hash mismatch",
    naming an object the build had no recorded reason to rebuild.

    So the consumer records the provider's body contract as a dependency of its own,
    and only when it actually baked one.  On one 875-source group that is 1116
    import records across 280 of 875 objects, naming 25 providers -- against 856
    objects that PUBLISH a body contract.  The difference between those two numbers is
    the whole point of doing this per consumer.

    The edge is a CONTENT dependency: it says the provider must be present and
    unchanged in this respect, not that it must be compiled first.  Ordering already
    comes from the compile-contract edge the previous pass recorded for the same
    provider, and spelling this one with that suffix would promote it to a required
    edge and collapse the component decomposition.

    The edge names the provider's whole body contract, but a consumer links against only
    the rows it baked, so the rows themselves are recorded beside the object in
    `<object>.body-contract-imports` (see write_aot_body_contract_imports()).  The
    scheduler watches those rows and nothing else: a provider recompiled in the other
    compile mode republishes a different body hash for symbols its parse could prove more
    or less about, and a consumer that baked none of them has nothing to relink.

    @param object_path the generated `.qo` whose symbol index names what it imports
    @param depfile the Make-format dependency file to extend; a missing file is a no-op
    @param depfile_target the target written before the colon when the file is rewritten
    @param error receives a description when the depfile cannot be read back or rewritten
    @param known_providers a source -> compile-contract-stamp map already built by the caller

    @return true on success, false with @a error set on failure */
static bool add_aot_body_contract_depfile_inputs(
        const std::string& object_path,
        const std::vector<std::string>& library_dirs,
        const std::string& depfile, const std::string& depfile_target,
        std::string& error,
        const AOTCompileContractProviderMap* known_providers = nullptr) {
    if (!depfile_declaration_contract_stamps || depfile.empty()
            || !is_file(depfile)) {
        return true;
    }

    QOLinkInputInfo consumer;
    if (!collect_qo_link_input(object_path.c_str(), consumer, error)) {
        return false;
    }

    std::set<std::string> owned_sources;
    for (size_t i = 0; i < consumer.index.defined.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT body-contract owned-source collection", error)) {
            return false;
        }
        const std::string& source = consumer.index.defined[i].source_file;
        if (!source.empty() && source.front() != '<') {
            owned_sources.insert(canonical_existing_path(source));
        }
    }

    // provider source -> the symbols whose body contract this object baked from it
    std::map<std::string, std::set<std::string>> baked_sources;
    for (size_t i = 0; i < consumer.index.imported.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT body-contract import collection", error)) {
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = consumer.index.imported[i];
        if (rec.body_contract_hash.empty()) {
            continue;
        }
        const std::string& provider = rec.provider_source_file;
        if (provider.empty() || provider.front() == '<') {
            continue;
        }
        std::string canon = canonical_existing_path(provider);
        if (!owned_sources.count(canon)) {
            baked_sources[std::move(canon)].insert(rec.qore_path);
        }
    }
    const std::string imports_path = object_path + AOTBodyContractImportsSuffix;
    if (baked_sources.empty()) {
        // a previous compile of this object may have baked some
        return remove_aot_body_contract_imports(imports_path, error);
    }

    AOTCompileContractProviderMap local_providers;
    if (!known_providers) {
        std::vector<std::string> provider_objects;
        collect_qo_library_inputs(provider_objects, library_dirs, object_path);
        if (!build_aot_compile_contract_provider_map(provider_objects,
                local_providers, error)) {
            return false;
        }
        known_providers = &local_providers;
    }

    static const std::string compile_suffix = ".compile-contract.stamp";
    static const std::string body_suffix = ".body-contract.stamp";

    std::vector<std::string> deps;
    read_make_depfile_inputs(depfile, deps);
    std::set<std::string> present;
    for (size_t i = 0; i < deps.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT body-contract depfile scan", error)) {
            return false;
        }
        present.insert(deps[i]);
    }
    bool changed = false;
    size_t provider_i = 0;
    std::vector<std::string> import_rows;
    for (const auto& baked : baked_sources) {
        const std::string& provider = baked.first;
        if (!qo_link_check_cancel(provider_i++,
                "AOT body-contract depfile merge", error)) {
            return false;
        }
        if (known_providers->ambiguous_sources.count(provider)) {
            continue;
        }
        auto stamp = known_providers->stamps.find(provider);
        if (stamp == known_providers->stamps.end()) {
            continue;
        }
        const std::string& compile_stamp = stamp->second;
        if (compile_stamp.size() <= compile_suffix.size()
                || compile_stamp.compare(compile_stamp.size() - compile_suffix.size(),
                    compile_suffix.size(), compile_suffix)) {
            continue;
        }
        std::string body_stamp =
            compile_stamp.substr(0, compile_stamp.size() - compile_suffix.size())
            + body_suffix;
        if (!is_file(body_stamp)) {
            continue;
        }
        size_t symbol_i = 0;
        for (const std::string& qore_path : baked.second) {
            if (!qo_link_check_cancel(symbol_i++, "AOT body-contract import collection", error)) {
                return false;
            }
            std::string row = "import\t";
            append_aot_contract_field(row, body_stamp);
            append_aot_contract_field(row, qore_path);
            import_rows.push_back(std::move(row));
        }
        if (present.insert(body_stamp).second) {
            deps.push_back(std::move(body_stamp));
            changed = true;
        }
    }
    // written before the depfile names the stamps it qualifies, so a scheduler that sees the edge sees the rows
    if (!write_aot_body_contract_imports(imports_path, import_rows, error)) {
        return false;
    }
    if (!changed) {
        return true;
    }
    std::sort(deps.begin(), deps.end());
    if (!write_depfile_list(depfile.c_str(), depfile_target, deps)) {
        error = "cannot add AOT body contracts to depfile '" + depfile + "'";
        return false;
    }
    return true;
}

//! Suffix of the sidecar naming the sources an object's code needs declared when it is loaded
static const char AOTLoadRequiresSuffix[] = ".load-requires";

//! The build group's source-symbol manifest, read once; nullptr when the compile was given none
static const QoreAOTSourceSymbolManifest* qcc_source_symbol_manifest(std::string& error) {
    static QoreAOTSourceSymbolManifest manifest;
    static bool loaded = false;
    if (!source_symbol_manifest_path) {
        return nullptr;
    }
    if (!loaded) {
        if (!read_source_symbol_manifest(source_symbol_manifest_path, manifest, error)) {
            return nullptr;
        }
        loaded = true;
    }
    return &manifest;
}

//! The one source declaring \a path in \a symbols, or an empty string
/** Resolved as a source parse resolves a deferred build-group symbol: by its full path, else -- for a name
    written without its namespace, or with a namespace the declaration does not spell the same way -- by the
    last segment when exactly one declaration carries it.  A symbol two sources declare names no provider.
*/
static std::string qcc_source_symbol_provider(const QoreAOTSourceSymbolMap& symbols, std::string path) {
    while (path.size() > 2 && path[0] == ':' && path[1] == ':') {
        path.erase(0, 2);
    }
    if (path.empty()) {
        return std::string();
    }
    auto i = symbols.find(path);
    if (i != symbols.end()) {
        return i->second.size() == 1 ? *i->second.begin() : std::string();
    }
    size_t pos = path.rfind("::");
    std::string name = pos == std::string::npos ? path : path.substr(pos + 2);
    const std::unordered_set<std::string>* unique = nullptr;
    for (const auto& symbol : symbols) {
        size_t symbol_pos = symbol.first.rfind("::");
        if ((symbol_pos == std::string::npos ? symbol.first : symbol.first.substr(symbol_pos + 2)) != name) {
            continue;
        }
        if (unique) {
            return std::string();
        }
        unique = &symbol.second;
    }
    return unique && unique->size() == 1 ? *unique->begin() : std::string();
}

//! The build-group source that declares what an import record names, or an empty string
/** A call the compile resolved against a preloaded object records its provider; a reference the compile
    deferred to link time -- a class it constructs or names as a type -- records only the path, and its provider
    is looked up in the build group's source-symbol manifest.  A member is provided by the source declaring its
    class.
*/
static std::string qcc_import_provider_source(const QoreAOTSymbolIndexRecord& rec,
        const QoreAOTSourceSymbolManifest* manifest) {
    if (!rec.provider_source_file.empty() && rec.provider_source_file.front() != '<') {
        return canonical_existing_path(rec.provider_source_file);
    }
    if (!manifest) {
        return std::string();
    }
    // a method path can carry its signature, whose parameter types contain "::" of their own
    std::string path = rec.qore_path.substr(0, rec.qore_path.find('('));
    switch (rec.kind) {
        case QoreAOTSymbolKind::CLASS:
            return qcc_source_symbol_provider(manifest->classes, path);
        case QoreAOTSymbolKind::HASHDECL:
            return qcc_source_symbol_provider(manifest->hashdecls, path);
        case QoreAOTSymbolKind::FUNCTION:
            return qcc_source_symbol_provider(manifest->functions, path);
        case QoreAOTSymbolKind::GLOBAL:
            return qcc_source_symbol_provider(manifest->globals, path);
        case QoreAOTSymbolKind::METHOD:
        case QoreAOTSymbolKind::STATIC_METHOD:
        case QoreAOTSymbolKind::CONSTRUCTOR:
        case QoreAOTSymbolKind::STATIC_VAR:
        case QoreAOTSymbolKind::CONSTANT: {
            size_t pos = path.rfind("::");
            if (pos == std::string::npos || !pos) {
                return std::string();
            }
            return qcc_source_symbol_provider(manifest->classes, path.substr(0, pos));
        }
        default:
            return std::string();
    }
}

//! Records the build-group sources an object's code needs declared wherever it is loaded.
/** An object preloaded into another compile is not only declared there: parse commit runs initializers, and code
    they reach in a preloaded object is that object's source-stripped IR, which registers only in a Program that
    declares every class and function it calls.  Those providers are not build dependencies -- a late-bound call
    bakes nothing of its target, so the object need not be rebuilt when the target changes -- and so the depfile
    does not name them, and a whole-group parse and a standalone compile do not even agree on whether they appear
    there.  The scheduler closes a preload set over this record as well as over the depfile.

    Format 1, one row per provider source after the header, the field length-prefixed as in the contracts:

        require\t<n>:<provider source path>

    Written only if the content changed, and removed when the object requires nothing from another source.

    @param object_path the generated `.qo` whose symbol index names what it imports
    @param error receives a description on failure

    @return true on success, false with @a error set on failure */
static bool write_aot_load_requires(const std::string& object_path, std::string& error) {
    const std::string path = object_path + AOTLoadRequiresSuffix;
    if (!depfile_declaration_contract_stamps) {
        return true;
    }
    const QoreAOTSourceSymbolManifest* manifest = qcc_source_symbol_manifest(error);
    if (!manifest && !error.empty()) {
        return false;
    }

    QOLinkInputInfo consumer;
    if (!collect_qo_link_input(object_path.c_str(), consumer, error)) {
        return false;
    }
    std::set<std::string> owned_sources;
    for (size_t i = 0; i < consumer.index.defined.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT load-requires owned-source collection", error)) {
            return false;
        }
        const std::string& source = consumer.index.defined[i].source_file;
        if (!source.empty() && source.front() != '<') {
            owned_sources.insert(canonical_existing_path(source));
        }
    }
    std::set<std::string> providers;
    for (size_t i = 0; i < consumer.index.imported.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT load-requires collection", error)) {
            return false;
        }
        const QoreAOTSymbolIndexRecord& rec = consumer.index.imported[i];
        std::string provider = qcc_import_provider_source(rec, manifest);
        if (provider.empty() || owned_sources.count(provider)) {
            continue;
        }
        if (!rec.consumer_source_file.empty()
                && canonical_existing_path(rec.consumer_source_file) == provider) {
            continue;
        }
        providers.insert(std::move(provider));
    }
    if (providers.empty()) {
        if (!unlink(path.c_str()) || errno == ENOENT) {
            return true;
        }
        error = "cannot remove stale load requirements '" + path + "': " + strerror(errno);
        return false;
    }
    std::string content = "format=1\n";
    for (const std::string& provider : providers) {
        content += "require\t";
        append_aot_contract_field(content, provider);
        content.push_back('\n');
    }
    return write_generated_file_if_changed(path, content, error);
}

static bool rewrite_depfile_source_content_stamps(
        const std::string& depfile, const std::string& depfile_target,
        std::string& error) {
    if (depfile_source_content_stamps.empty() || depfile.empty()
            || !is_file(depfile)) {
        return true;
    }

    std::vector<std::string> deps;
    read_make_depfile_inputs(depfile, deps);
    bool changed = false;
    for (size_t i = 0; i < deps.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "qcc source-content depfile rewrite", error)) {
            return false;
        }
        auto stamp = depfile_source_content_stamps.find(
            canonical_existing_path(deps[i]));
        if (stamp != depfile_source_content_stamps.end()) {
            deps[i] = stamp->second;
            changed = true;
        }
    }
    if (changed && !write_depfile_list(depfile.c_str(), depfile_target, deps)) {
        error = "cannot rewrite source dependencies in depfile '" + depfile
            + "'";
        return false;
    }
    return true;
}

static bool validate_script_object_body_contracts(
        const std::vector<std::string>& object_paths) {
    bool initialize_qore = !q_libqore_initalized();
    if (initialize_qore) {
        qcc_init_qore();
    }

    std::vector<QOLinkInputInfo> inputs;
    inputs.reserve(object_paths.size());
    std::string error;
    for (size_t i = 0; i < object_paths.size(); ++i) {
        if (!qo_link_check_cancel(i,
                "AOT executable body contract input collection", error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            if (initialize_qore) {
                qore_cleanup();
            }
            return false;
        }
        QOLinkInputInfo input;
        if (!collect_qo_link_input(object_paths[i].c_str(), input, error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            if (initialize_qore) {
                qore_cleanup();
            }
            return false;
        }
        inputs.push_back(std::move(input));
    }

    QOLinkPlan plan;
    if (!validate_qo_link_inputs(inputs, plan, error)) {
        fprintf(stderr, "error: %s\n", error.c_str());
        if (initialize_qore) {
            qore_cleanup();
        }
        return false;
    }

    auto body_issues = [&error](const std::vector<QOLinkIssue>& issues,
            std::vector<QOLinkIssue>& result) {
        for (size_t i = 0; i < issues.size(); ++i) {
            if (!qo_link_check_cancel(i,
                    "AOT executable body contract issue filtering", error)) {
                return false;
            }
            if (issues[i].dependency_class == "native_body") {
                result.push_back(issues[i]);
            }
        }
        return true;
    };
    std::vector<QOLinkIssue> unresolved;
    std::vector<QOLinkIssue> ambiguous;
    std::vector<QOLinkIssue> mismatches;
    if (!body_issues(plan.unresolved_imports, unresolved)
            || !body_issues(plan.ambiguous_imports, ambiguous)
            || !body_issues(plan.hash_mismatches, mismatches)) {
        fprintf(stderr, "error: %s\n", error.c_str());
        if (initialize_qore) {
            qore_cleanup();
        }
        return false;
    }
    bool valid = unresolved.empty() && ambiguous.empty()
        && mismatches.empty();
    if (!valid) {
        print_qo_link_issues("unresolved body contract", unresolved);
        print_qo_link_issues("ambiguous body contract", ambiguous);
        print_qo_link_issues("body contract hash mismatch", mismatches);
    }
    if (initialize_qore) {
        qore_cleanup();
    }
    return valid;
}

//! Loads the AOT metadata blobs embedded in a script-context `.qo` fragment
/** @param path the fragment
    @param blobs receives the fragment's metadata blobs
    @param error receives the reason on failure

    @return true on success; a fragment without any metadata blob is an error
*/
static bool load_script_object_metadata_blobs(const std::string& path, std::vector<AOTDumpMetadataBlob>& blobs,
        std::string& error) {
    std::string contents;
    if (!read_file(path.c_str(), contents)) {
        error = "cannot read input object: " + path;
        return false;
    }
    auto binary_or = llvm::object::createBinary(path);
    if (!binary_or) {
        error = "cannot read object file '" + path + "': " + llvm::toString(binary_or.takeError());
        return false;
    }
    auto* obj = llvm::dyn_cast<llvm::object::ObjectFile>(binary_or->getBinary());
    if (!obj) {
        error = "input is not a relocatable object file: " + path;
        return false;
    }
    std::set<std::string> seen_blobs;
    extract_aot_metadata_from_object(*obj, blobs, seen_blobs);
    scan_aot_metadata_blobs(contents, blobs, seen_blobs);
    if (blobs.empty()) {
        error = "input has no AOT metadata blob: " + path;
        return false;
    }
    return true;
}

//! Returns the parse options a Program running the given script-context `.qo` fragments needs
/** Each fragment records the parse options it was compiled with, including the Program-level directives in its source
    (e.g. \c %allow-debugger, \c %new-style, or a \c %no-... restriction).  In a shared parse a directive in any file
    applies to the whole Program, so the linked Program gets the union of the fragments' options.

    @param object_paths the fragments
    @param po receives the parse options
    @param error receives the reason on failure

    @return true on success
*/
static bool collect_script_object_parse_options(const std::vector<std::string>& object_paths,
        QoreParseOptions& po, std::string& error) {
    po = QoreParseOptions();
    for (const std::string& path : object_paths) {
        std::vector<AOTDumpMetadataBlob> blobs;
        if (!load_script_object_metadata_blobs(path, blobs, error)) {
            return false;
        }
        for (const AOTDumpMetadataBlob& blob : blobs) {
            QoreAOTBinaryReader reader;
            std::string reader_error;
            if (!reader.open(blob.bytes.data(), static_cast<uint32_t>(blob.bytes.size()), reader_error)) {
                error = "invalid AOT metadata in '" + path + "' (" + blob.source + "): " + reader_error;
                return false;
            }
            const QoreAOTBinaryHeader& hdr = reader.getHeader();
            po |= QoreParseOptions(static_cast<int64>(hdr.parse_options_lo),
                static_cast<int64>(hdr.parse_options_hi));
        }
    }
    return true;
}

//! A function in a script-context `.qo` fragment that uses a top-level local variable of its source
struct ScriptObjectTopLevelLocalUse {
    //! the fragment, with the source it was compiled from
    std::string object;
    //! the description of the function, method, closure or initializer using the variable
    std::string function;
    //! the top-level local variable
    std::string variable;

    bool operator<(const ScriptObjectTopLevelLocalUse& other) const {
        return std::tie(object, function, variable) < std::tie(other.object, other.function, other.variable);
    }
};

//! Returns the user-facing description of a compiled function named in a SLOT_MAPS entry
/** Compiled initializers and closures are named by internal keys (see QoreAOT.cpp); static methods carry a
    \c _static_ marker before the method name.

    @param name the name recorded in the slot map

    @return the description, e.g. \c "method 'C::m()'" or \c "a closure in 'mk()'"
*/
static std::string script_object_function_description(const std::string& name) {
    // strips a namespace path with an empty root ("::x" or "::::x" for a root namespace item)
    auto item_path = [](std::string path) {
        while (path.compare(0, 2, "::") == 0) {
            path.erase(0, 2);
        }
        return path;
    };
    auto starts = [&name](const char* prefix) {
        return name.compare(0, strlen(prefix), prefix) == 0;
    };
    if (starts("__gvar_init::")) {
        return "the initializer of global variable '" + item_path(name.substr(strlen("__gvar_init::"))) + "'";
    }
    if (starts("__svar_init::")) {
        return "the initializer of static variable '" + item_path(name.substr(strlen("__svar_init::"))) + "'";
    }
    if (starts("__const_init::")) {
        return "the initializer of constant '" + item_path(name.substr(strlen("__const_init::"))) + "'";
    }
    if (starts("__aot_closure::")) {
        // "__aot_closure::<owner>::<expression index>"
        std::string owner = name.substr(strlen("__aot_closure::"));
        size_t pos = owner.rfind("::");
        if (pos != std::string::npos) {
            owner.erase(pos);
        }
        return "a closure in '" + item_path(owner) + "'";
    }
    std::string display = name;
    size_t pos = display.find("::_static_");
    if (pos != std::string::npos) {
        display.erase(pos + 2, strlen("_static_"));
        return "static method '" + display + "'";
    }
    if (display.find("::") != std::string::npos) {
        return "method '" + display + "'";
    }
    return "function '" + display + "'";
}

//! Collects the functions in one AOT metadata blob that use a top-level local variable
/** A compiled function, method or closure that uses a top-level local variable of its source records the variable
    in its slot map with \c QORE_AOT_LOCAL_SLOT_TOP_LEVEL (closures bind through the slot of the function that
    contains them).

    @param reader the opened blob
    @param object the fragment the blob was read from
    @param uses receives the uses found
    @param error receives the reason on failure

    @return true on success, false if the SLOT_MAPS section is malformed or the operation was cancelled
*/
static bool collect_blob_top_level_local_uses(const QoreAOTBinaryReader& reader, const std::string& object,
        std::set<ScriptObjectTopLevelLocalUse>& uses, std::string& error) {
    const QoreAOTSectionHeader* sec = reader.findSection(QoreAOTSectionType::SLOT_MAPS);
    if (!sec) {
        return true;
    }
    const uint8_t* p = reader.getSectionData(*sec);
    if (!p) {
        error = "invalid SLOT_MAPS section in '" + object + "'";
        return false;
    }
    const uint8_t* end = p + sec->size;
    uint32_t num_funcs = 0;
    if (!dump_read_u32(p, end, num_funcs)) {
        error = "truncated SLOT_MAPS header in '" + object + "'";
        return false;
    }
    const bool has_decl_ordinal = (reader.getHeader().feature_flags & QORE_AOT_FEAT_LOCAL_DECL_ORDINAL) != 0;
    for (uint32_t f = 0; f < num_funcs; ++f) {
        if (!qo_link_check_cancel(f, "AOT executable top-level local check", error)) {
            return false;
        }
        uint32_t entry_size = 0;
        if (!dump_read_u32(p, end, entry_size) || static_cast<size_t>(end - p) < entry_size) {
            error = "truncated SLOT_MAPS entry in '" + object + "'";
            return false;
        }
        const uint8_t* entry_end = p + entry_size;
        const char* fname = nullptr;
        uint16_t num_locals = 0;
        // function name, then the local, global, expression, statement, regex and body-local slot counts,
        // the unsupported-expression flag and the LValuePath count
        if (!dump_skip_string_ref(reader, p, entry_end, &fname)
                || !dump_read_u16(p, entry_end, num_locals)
                || !dump_skip_bytes(p, entry_end, 5 * sizeof(uint16_t) + 2 * sizeof(uint8_t))) {
            error = "malformed SLOT_MAPS entry " + std::to_string(f) + " in '" + object + "'";
            return false;
        }
        for (uint16_t i = 0; i < num_locals; ++i) {
            if (!qo_link_check_cancel(i, "AOT executable top-level local slot check", error)) {
                return false;
            }
            const char* lname = nullptr;
            uint8_t lflags = 0;
            if (!dump_skip_string_ref(reader, p, entry_end, &lname)
                    || !dump_skip_string_ref(reader, p, entry_end)
                    || !dump_read_u8(p, entry_end, lflags)
                    || !dump_skip_bytes(p, entry_end, sizeof(uint16_t) + (has_decl_ordinal ? sizeof(uint32_t) : 0))) {
                error = "malformed local slot " + std::to_string(i) + " of SLOT_MAPS entry " + std::to_string(f)
                    + " in '" + object + "'";
                return false;
            }
            if (lflags & QORE_AOT_LOCAL_SLOT_TOP_LEVEL) {
                uses.insert({object, script_object_function_description(fname && *fname ? fname : "<unnamed>"),
                    lname && *lname ? lname : "<unnamed>"});
            }
        }
        p = entry_end;
    }
    return true;
}

//! Rejects script-context `.qo` fragments whose top-level code an executable linked from them would skip
/** An executable linked from script objects (`qcc -o exe a.qo b.qo`, or a multi-source executable) registers the
    objects and then runs only its entry function: the top-level statements of the objects' sources never run.  Two
    kinds of fragment content would therefore change the program's behavior silently, where the interpreter runs
    the same code correctly, and the link is refused for either:
    - a function, method or closure using a top-level local variable: the variable is never created, so the
      function reads no value and its updates are lost; found through the slot maps, so it is also detected in
      fragments built before fragments recorded their top-level statements
    - a top-level statement that executes code (an assignment, a call, a local variable initialization, a control
      statement): recorded by the fragment in its UNRUN_TOP_LEVEL_CODE section.  Declarations without an
      initializer execute nothing, and the initializers of global variables are carried by the fragment and run
      when it is registered, so neither is reported.  A script commonly ends with a call of its entry function
      without arguments (<tt>main();</tt>) so that the interpreter runs it; the executable makes exactly that call,
      so the first such call (in link order) is exempt, and any further one is reported

    Hosts that register fragments themselves (the `--link-qo` and custom C++ host workflows) define what runs and
    are not affected.

    @param object_paths the fragments being linked
    @param entry the entry function the executable calls
    @param error receives the diagnostic

    @return true if the fragments contain no top-level code that the executable would skip
*/
static bool check_script_object_top_level_code(const std::vector<std::string>& object_paths, const char* entry,
        std::string& error) {
    std::string entry_name = entry ? entry : "";
    while (!entry_name.compare(0, 2, "::")) {
        entry_name.erase(0, 2);
    }
    bool entry_call_seen = false;
    std::set<ScriptObjectTopLevelLocalUse> uses;
    std::vector<std::pair<std::string, QoreAOTUnrunTopLevelStatement>> unrun;
    for (size_t i = 0; i < object_paths.size(); ++i) {
        if (!qo_link_check_cancel(i, "AOT executable top-level code check", error)) {
            return false;
        }
        const std::string& path = object_paths[i];
        std::vector<AOTDumpMetadataBlob> blobs;
        if (!load_script_object_metadata_blobs(path, blobs, error)) {
            return false;
        }
        for (const AOTDumpMetadataBlob& blob : blobs) {
            QoreAOTBinaryReader reader;
            std::string reader_error;
            if (!reader.open(blob.bytes.data(), static_cast<uint32_t>(blob.bytes.size()), reader_error)) {
                error = "invalid AOT metadata in '" + path + "' (" + blob.source + "): " + reader_error;
                return false;
            }
            // name the source as well: a multi-source executable links temporary objects
            const char* label = reader.getLabel();
            std::string object = label && *label && path.find(label) == std::string::npos
                ? path + " (" + label + ")"
                : path;
            if (!collect_blob_top_level_local_uses(reader, object, uses, error)) {
                return false;
            }
            std::vector<QoreAOTUnrunTopLevelStatement> statements;
            if (!readAOTUnrunTopLevelCode(reader, statements, reader_error)) {
                error = "invalid AOT metadata in '" + path + "' (" + blob.source + "): " + reader_error;
                return false;
            }
            for (QoreAOTUnrunTopLevelStatement& stmt : statements) {
                if (!entry_call_seen && !stmt.call.empty() && stmt.call == entry_name) {
                    entry_call_seen = true;
                    continue;
                }
                unrun.emplace_back(path, std::move(stmt));
            }
        }
    }
    if (uses.empty() && unrun.empty()) {
        return true;
    }
    error = "an executable linked from script objects runs only its entry function; the top-level statements of "
        "its sources never run, so it would silently skip code that the sources rely on:";
    for (const ScriptObjectTopLevelLocalUse& use : uses) {
        error += "\n  " + use.object + ": " + use.function + " uses top-level local variable '" + use.variable
            + "', which is never created";
    }
    for (const auto& [object, stmt] : unrun) {
        error += "\n  " + object + ": " + stmt.file + ":" + std::to_string(stmt.line) + ": " + stmt.description
            + " never runs";
    }
    error += "\nmove top-level code into a function (for example the entry function), declare variables that "
        "functions share as global variables (for example 'our int counter = 5;'), whose initializers do run, or "
        "compile a single script on its own to an executable, which runs its top-level code";
    return false;
}

//! Link script-context `.qo` fragments into an executable.
static int link_script_objects_to_executable(const std::string& output,
        const std::vector<std::string>& object_paths,
        const std::string& glue_path, const char* entry,
        const char* mode_label, int compiled_count = -1, int opt_level = -1,
        bool include_source = false) {
    if (object_paths.empty()) {
        fprintf(stderr, "error: %s link failed for output '%s': no .qo inputs\n",
            mode_label, output.c_str());
        return 1;
    }
    if (!validate_script_object_body_contracts(object_paths)) {
        return 1;
    }
    {
        std::string tl_error;
        if (!check_script_object_top_level_code(object_paths, entry, tl_error)) {
            fprintf(stderr, "error: %s link failed for output '%s': %s\n", mode_label, output.c_str(),
                tl_error.c_str());
            return 1;
        }
    }
    // the Program runs with the options the fragments were compiled with, not a fixed set
    QoreParseOptions link_po;
    {
        std::string po_error;
        if (!collect_script_object_parse_options(object_paths, link_po, po_error)) {
            fprintf(stderr, "error: %s link failed for output '%s': %s\n", mode_label, output.c_str(),
                po_error.c_str());
            return 1;
        }
    }

    FILE* glue = fopen(glue_path.c_str(), "w");
    if (!glue) {
        fprintf(stderr,
            "error: %s link failed for output '%s': cannot write glue file '%s': %s\n",
            mode_label, output.c_str(), glue_path.c_str(), strerror(errno));
        return 1;
    }
    fprintf(glue,
        "// Auto-generated by qcc %s - do not edit.\n"
        "// C++ host for %zu .qo input%s.\n"
        "#include <qore/Qore.h>\n"
        "#include <qore/QoreAOT.h>\n"
        "#include <stdio.h>\n\n",
        QCC_VERSION, object_paths.size(),
        object_paths.size() == 1 ? "" : "s");

    std::vector<std::string> sans;
    sans.reserve(object_paths.size());
    fprintf(glue, "extern \"C\" {\n");
    for (const auto& op : object_paths) {
        std::string san = sanitize_c_identifier(basename_no_ext(op));
        fprintf(glue,
            "    void qore_%s_%s_script_register(QoreProgram*);\n",
            san.c_str(), san.c_str());
        sans.push_back(std::move(san));
    }
    fprintf(glue, "}\n\n");

    fprintf(glue,
        "int main(int /*argc*/, char** /*argv*/) {\n"
        "    qore_init(QL_GPL, \"UTF-8\", true);\n"
        "    QoreProgram* pgm = qore_create_program_ext(\n"
        "        (int64_t)0x%016llxULL, (int64_t)0x%016llxULL);\n"
        "    if (!pgm) {\n"
        "        fprintf(stderr, \"qore_create_program failed\\n\");\n"
        "        qore_cleanup();\n"
        "        qore_fork_child_quick_exit(1);\n"
        "        return 1;\n"
        "    }\n"
        "    qore_aot_script_begin_batch(pgm);\n",
        static_cast<unsigned long long>(link_po.getLo()), static_cast<unsigned long long>(link_po.getHi()));
    for (const auto& san : sans) {
        fprintf(glue,
            "    qore_%s_%s_script_register(pgm);\n",
            san.c_str(), san.c_str());
    }
    fprintf(glue,
        "    int rc = qore_aot_script_end_batch(pgm);\n"
        "    if (rc != 0) {\n"
        "        fprintf(stderr, \"batch flush failed: %%s\\n\",\n"
        "            qore_last_error(pgm));\n"
        "        qore_destroy_program(pgm);\n"
        "        qore_cleanup();\n"
        "        qore_fork_child_quick_exit(1);\n"
        "        return 1;\n"
        "    }\n"
        "    rc = qore_run_callable(pgm, \"%s\", NULL);\n"
        "    if (rc != 0) {\n"
        "        fprintf(stderr, \"entry %s returned %%d: %%s\\n\",\n"
        "            rc, qore_last_error(pgm));\n"
        "    }\n"
        "    qore_destroy_program(pgm);\n"
        "    qore_cleanup();\n"
        "    // a child process created with fork() whose modules requested it ends without running exit-time\n"
        "    // handlers, as when the main program of qore and qr ends (see qore_fork_child_exit_quickly())\n"
        "    qore_fork_child_quick_exit(rc);\n"
        "    return rc;\n"
        "}\n",
        entry, entry);

    if (fclose(glue) != 0) {
        fprintf(stderr,
            "error: %s link failed for output '%s': cannot close glue file '%s': %s\n",
            mode_label, output.c_str(), glue_path.c_str(), strerror(errno));
        return 1;
    }

    if (verbose) {
        printf("qcc link: emitted glue main %s (%zu .qo inputs, entry fn: %s)\n",
            glue_path.c_str(), object_paths.size(), entry);
    }

    std::string cxx;
    if (QoreEnvironmentValue env_cxx_holder("CXX"); const char* env_cxx = env_cxx_holder.c_str()) {
        cxx = env_cxx;
    } else {
        cxx = "g++";
    }
    std::vector<std::string> include_dirs;
    std::vector<std::string> lib_dirs;
    collect_qcc_link_paths(include_dirs, lib_dirs);

    std::string cmd = cxx + " -std=c++17";
    for (const auto& dir : include_dirs) {
        cmd += " -I" + shell_quote(dir);
    }
    cmd += " " + shell_quote(glue_path);
    for (const auto& op : object_paths) {
        cmd += " " + shell_quote(op);
    }
    append_qcc_link_flags(cmd, lib_dirs);
    cmd += " -o ";
    cmd += shell_quote(output);
    if (verbose) {
        for (const auto& dir : include_dirs) {
            printf("qcc link: include dir: %s\n", dir.c_str());
        }
        for (const auto& dir : lib_dirs) {
            printf("qcc link: library dir: %s\n", dir.c_str());
        }
        printf("qcc link: %s\n", cmd.c_str());
    }
    int link_rc;
    {
        // the linker gets a copy of the environment, which must not change while it is copied
        QoreEnvironmentReadLock env_lock;
        link_rc = std::system(cmd.c_str());
    }
    if (link_rc != 0) {
        fprintf(stderr,
            "error: %s link failed for output '%s' from %zu .qo objects using glue '%s' (rc=%d): %s\n",
            mode_label, output.c_str(), object_paths.size(),
            glue_path.c_str(), link_rc, cmd.c_str());
        return 1;
    }
    int64_t output_size = file_size(output);
    std::string mode_suffix;
    if (opt_level >= 0) {
        mode_suffix = " (-O" + std::to_string(opt_level);
        if (include_source) {
            mode_suffix += ", include-source";
        }
        mode_suffix += ")";
    }
    if (compiled_count >= 0) {
        if (output_size >= 0) {
            printf("qcc: %s%s: %lld bytes for %d Qore code variants (%zu .qo inputs, entry: %s): %s\n",
                mode_label, mode_suffix.c_str(), (long long)output_size, compiled_count,
                object_paths.size(), entry, output.c_str());
        } else {
            printf("qcc: %s%s: %d Qore code variants (%zu .qo inputs, entry: %s): %s\n",
                mode_label, mode_suffix.c_str(), compiled_count, object_paths.size(), entry, output.c_str());
        }
    } else if (output_size >= 0) {
        printf("qcc: %s%s: %lld bytes from %zu .qo input%s (entry: %s): %s\n",
            mode_label, mode_suffix.c_str(), (long long)output_size, object_paths.size(),
            object_paths.size() == 1 ? "" : "s", entry, output.c_str());
    } else {
        printf("qcc: %s%s: %zu .qo input%s (entry: %s): %s\n",
            mode_label, mode_suffix.c_str(), object_paths.size(), object_paths.size() == 1 ? "" : "s",
            entry, output.c_str());
    }
    return 0;
}

int main(int argc, char** argv) {
    qore_ensure_standard_fds();

    // Parse command-line options
    if (parse_options_cmdline(argc, argv) != 0) {
        return 1;
    }

    // Phase 1 compile-time opt: flags propagated to QoreAOT via env vars
    // (AOT layer already reads several QORE_AOT_* vars; this extends the set).
    if (strip_debug_info) {
        SystemEnvironment::set("QORE_AOT_NO_DEBUG_INFO", "1", 1);
    }
    if (time_trace_path) {
        SystemEnvironment::set("QORE_AOT_TIME_TRACE", time_trace_path, 1);
    }
    if (verbose) {
        SystemEnvironment::set("QORE_AOT_VERBOSE", "1", 1);
    }
    if (warnings_are_errors) {
        SystemEnvironment::set("QORE_AOT_WARNINGS_ARE_ERRORS", "1", 1);
    }
    if (metadata_compression) {
        SystemEnvironment::set("QORE_AOT_METADATA_COMPRESSION", metadata_compression, 1);
    }
    // Propagate the CLI flag's value to QORE_AOT_BIG_FN_THRESHOLD so
    // the IR-to-LLVM lowerer picks it up.  Overwrite the env only when
    // the user explicitly passed --big-fn-threshold on the command line;
    // otherwise leave any pre-existing shell-env value alone.  This
    // keeps the CLI default (200) from silently clobbering
    // `QORE_AOT_BIG_FN_THRESHOLD=50 qcc ...`, while still letting
    // `qcc --big-fn-threshold=N` take effect in shells that have a
    // different value set.
    if (big_fn_threshold > 0) {
        char buf[32];
        snprintf(buf, sizeof(buf), "%d", big_fn_threshold);
        SystemEnvironment::set("QORE_AOT_BIG_FN_THRESHOLD", buf, big_fn_threshold_cli_explicit);
    }
    // Propagate --jobs to QCC_JOBS so the backend-codegen path (emitObjectFile) picks it up.
    // An explicit flag overrides any pre-existing QCC_JOBS in the environment.
    if (aot_jobs > 0) {
        char jbuf[32];
        snprintf(jbuf, sizeof(jbuf), "%d", aot_jobs);
        SystemEnvironment::set("QCC_JOBS", jbuf, 1);
    }

    if (show_help) {
        print_usage(argv[0]);
        return 0;
    }

    if (show_version) {
        print_version();
        return 0;
    }

    if (show_targets) {
        QoreAOT::printSupportedTargets();
        return 0;
    }

    bool batch_compile_arguments = compile_only && !context_dir
        && (optind + 1 < argc);
    if (!file_prefix_maps.empty()) {
        // Incremental .qo workflows use physical source identities to preload and bind sibling
        // declarations. Deployment path maps apply to one final executable or whole module only.
        if (compile_only || context_dir || from_objects || archive_mode || link_qo
                || script_aggregate_symbol || optind + 1 != argc) {
            fprintf(stderr, "error: --file-prefix-map requires a single-source executable or whole-module "
                "build; incremental objects and object linking retain physical source identities\n");
            return 1;
        }
        // the prefixes match the canonical paths qcc names its inputs by as well
        QoreAOT::setFilePrefixMaps(with_canonical_file_prefixes(file_prefix_maps));
    }
    if (depfile_path && depfile_dir && !batch_compile_arguments) {
        fprintf(stderr,
            "error: --depfile and --depfile-dir are mutually exclusive "
            "outside batch compile mode\n");
        return 1;
    }
    if (depfile_target_path && !depfile_path) {
        fprintf(stderr,
            "error: --depfile-target requires --depfile=FILE\n");
        return 1;
    }
    if (batch_build_sidecars && !depfile_dir) {
        fprintf(stderr,
            "error: --batch-build-sidecars requires --depfile-dir=DIR\n");
        return 1;
    }
    if (skip_if_manifest_current && !write_manifest_path) {
        fprintf(stderr,
            "error: --skip-if-manifest-current requires --write-manifest=FILE\n");
        return 1;
    }
    if (depfile_source_content_map_path && !depfile_path && !depfile_dir) {
        fprintf(stderr,
            "error: --depfile-source-content-map requires --depfile or --depfile-dir\n");
        return 1;
    }
    // The map is the group's list of its own sources, and so the only thing that says which
    // dependency is a group member whose declaration contract may stand in for its source.
    if (depfile_declaration_contract_stamps && !depfile_source_content_map_path) {
        fprintf(stderr, "error: --depfile-declaration-contract-stamps requires "
            "--depfile-source-content-map=FILE\n");
        return 1;
    }
    std::string depfile_source_content_error;
    if (!load_depfile_source_content_map(depfile_source_content_error)) {
        fprintf(stderr, "error: %s\n", depfile_source_content_error.c_str());
        return 1;
    }

    if (dump_index_json) {
        if (optind + 1 != argc) {
            fprintf(stderr, "error: --dump-index-json requires exactly one binary/object path\n");
            return 1;
        }
        qcc_init_qore();
        int rc = dump_aot_index_json_for_file(argv[optind]);
        qore_cleanup();
        return rc;
    }

    if (dump_symbols || dump_sections) {
        dump_info = true;
    }
    if (dump_info) {
        if (optind >= argc) {
            fprintf(stderr, "error: --dump-info requires at least one binary/object path\n");
            return 1;
        }
        qcc_init_qore();
        int rc = 0;
        for (int i = optind; i < argc; ++i) {
            if (dump_aot_info_for_file(argv[i])) {
                rc = 1;
            }
        }
        qore_cleanup();
        return rc;
    }

    if ((link_aggregate_symbol || qolink_map_path) && !link_qo) {
        fprintf(stderr,
            "error: --aggregate-symbol and --qolink-map are only valid with --link-qo\n");
        return 1;
    }
    if ((strict_call_relocations || allow_unresolved_qo_imports) && !link_qo) {
        fprintf(stderr,
            "error: --strict-call-relocations and --allow-unresolved-imports are only valid with --link-qo\n");
        return 1;
    }
    if ((batch_script_aggregate_symbol == nullptr)
            != (batch_script_aggregate_output == nullptr)) {
        fprintf(stderr,
            "error: --batch-script-aggregate and --batch-script-aggregate-output"
            " must be used together\n");
        return 1;
    }
    if (batch_script_aggregate_symbol
            && (!compile_only || !batch_output_dir)) {
        fprintf(stderr,
            "error: --batch-script-aggregate requires -c and --output-dir\n");
        return 1;
    }
    if (!batch_script_aggregate_manifest_inputs.empty()
            && !batch_script_aggregate_symbol) {
        fprintf(stderr,
            "error: --batch-script-aggregate-manifest-input requires "
            "--batch-script-aggregate\n");
        return 1;
    }
    if (batch_script_aggregate_symbol && optind + 1 >= argc) {
        fprintf(stderr,
            "error: --batch-script-aggregate requires at least two source files\n");
        return 1;
    }
    if (script_aggregate_native_registers && !script_aggregate_symbol
            && !batch_script_aggregate_symbol) {
        fprintf(stderr,
            "error: --script-aggregate-native-registers requires a script aggregate mode\n");
        return 1;
    }

    if (link_qo) {
        if (compile_only || module_mode || archive_mode || from_objects || context_dir
                || batch_output_dir || script_aggregate_symbol
                || batch_script_aggregate_symbol) {
            fprintf(stderr,
                "error: --link-qo cannot be combined with compile/module/archive/source aggregate modes\n");
            return 1;
        }
        if (!output_path) {
            fprintf(stderr, "error: --link-qo requires -o/--output\n");
            return 1;
        }
        if (!link_aggregate_symbol || !*link_aggregate_symbol) {
            fprintf(stderr, "error: --link-qo requires --aggregate-symbol=SYM\n");
            return 1;
        }
        if (optind >= argc) {
            fprintf(stderr, "error: --link-qo requires at least one .qo input\n");
            return 1;
        }

        std::string map_path = qolink_map_path ? qolink_map_path
            : std::string(output_path) + ".qolink.json";
        QCCBuildManifest manifest;
        manifest.kind = "link-qo";
        manifest.output = output_path;
        manifest.index_json = write_index_json_path ? write_index_json_path : "";
        manifest.depfile = depfile_path ? depfile_path : "";
        manifest.link_map = map_path;
        manifest.aggregate_symbol = link_aggregate_symbol;
        add_existing_qo_inputs_from_args(manifest.inputs, optind, argc, argv);
        capture_qcc_input_snapshots(manifest);
        QCCFileFingerprint output_before = qcc_file_fingerprint(manifest.output);
        if (skip_if_manifest_current && qcc_manifest_current(manifest, argv[0])) {
            if (qcc_output_verbose()) {
                printf("qcc: manifest current, skipped qo link aggregate: %s\n", output_path);
            }
            std::string error;
            QCCFinishResult finish = finish_qcc_build(
                manifest, argv[0], output_before, false, true, true, error);
            if (finish != QCCFinishResult::Success) {
                fprintf(stderr, "error: %s\n", error.c_str());
                return qcc_finish_error_exit(finish);
            }
            return 0;
        }

        std::vector<QOLinkInputInfo> inputs;
        inputs.reserve(argc - optind);
        qcc_init_qore();
        for (int i = optind; i < argc; ++i) {
            std::string error;
            if (!qo_link_check_cancel(static_cast<size_t>(i - optind),
                    "AOT qo-link input collection", error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                qore_cleanup();
                return 1;
            }
            if (!has_qo_extension(argv[i])) {
                fprintf(stderr, "error: --link-qo input '%s' must end in .qo\n", argv[i]);
                qore_cleanup();
                return 1;
            }
            char* resolved = realpath(argv[i], nullptr);
            if (!resolved) {
                fprintf(stderr, "error: cannot resolve '%s': %s\n", argv[i], strerror(errno));
                qore_cleanup();
                return 1;
            }
            QOLinkInputInfo input;
            bool ok = collect_qo_link_input(resolved, input, error);
            free(resolved);
            if (!ok) {
                fprintf(stderr, "error: %s\n", error.c_str());
                qore_cleanup();
                return 1;
            }
            inputs.push_back(std::move(input));
        }

        QOLinkPlan plan;
        std::string error;
        if (!validate_qo_link_inputs(inputs, plan, error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        bool import_errors = (!allow_unresolved_qo_imports && !plan.unresolved_imports.empty())
            || !plan.ambiguous_imports.empty() || !plan.hash_mismatches.empty();
        bool call_relocation_errors = strict_call_relocations
            && (!plan.unresolved_call_relocations.empty()
                || !plan.ambiguous_call_relocations.empty()
                || !plan.call_relocation_hash_mismatches.empty());
        if (import_errors || call_relocation_errors) {
            if (import_errors) {
                // an aggregate of part of a group may leave imports to the rest of it unresolved; listing them
                // as errors would hide the issue that actually failed the link among them
                if (!allow_unresolved_qo_imports) {
                    print_qo_link_issues("unresolved import", plan.unresolved_imports);
                }
                print_qo_link_issues("ambiguous import", plan.ambiguous_imports);
                print_qo_link_issues("hash mismatch", plan.hash_mismatches);
            }
            if (call_relocation_errors) {
                print_qo_link_call_relocation_issues("unresolved", plan.unresolved_call_relocations);
                print_qo_link_call_relocation_issues("ambiguous", plan.ambiguous_call_relocations);
                print_qo_link_call_relocation_issues("hash mismatch", plan.call_relocation_hash_mismatches);
            }
            qore_cleanup();
            return 1;
        }

        std::vector<std::string> register_symbols;
        register_symbols.reserve(inputs.size());
        for (size_t i = 0; i < inputs.size(); ++i) {
            if (!qo_link_check_cancel(i, "AOT qo-link register-symbol collection", error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                qore_cleanup();
                return 1;
            }
            register_symbols.push_back(inputs[i].register_symbol);
        }

        if (!QoreAOT::compileScriptRegisterAggregate(register_symbols, output_path,
                link_aggregate_symbol, error, opt_level, target_triple)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }

        if (!write_qo_link_map(map_path, output_path, link_aggregate_symbol,
                inputs, plan, error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        std::vector<std::string> depfile_inputs = qcc_depfile_explicit_inputs(manifest.inputs);
        if (depfile_path && !write_depfile_list(depfile_path,
                qcc_depfile_target(output_path), depfile_inputs)) {
            qore_cleanup();
            return 1;
        }
        QCCFinishResult finish = finish_qcc_build(
            manifest, argv[0], output_before, true, false, true, error);
        if (finish != QCCFinishResult::Success) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return qcc_finish_error_exit(finish);
        }

        if (qcc_output_verbose()) {
            printf("qcc: linked qo aggregate from %zu .qo input%s (-O%d): %s\n",
                inputs.size(), inputs.size() == 1 ? "" : "s", opt_level, output_path);
            printf("qcc: wrote qo link map: %s\n", map_path.c_str());
        }
        qore_cleanup();
        return 0;
    }

    // Phase C Item 2: link-mode — `qcc -o <binary> *.qo` emits a
    // synthesised C++ main (qore_init → create_program → begin_batch
    // → per-.qo qore_<sanfile>_<sanfile>_script_register calls →
    // end_batch → run entry fn → destroy_program → cleanup) and
    // invokes $CXX (fallback g++) to link the .qo set + -lqore into
    // a standalone executable.  Replaces the hand-written C++ main
    // pattern `examples/aot/qoa_link_test.cpp` documents.
    //
    // Entered when: `-o <file>` is set, all positional inputs end
    // in `.qo`, and no competing mode is active (-c, -m, -a, -F).
    if (output_path && !compile_only && !module_mode && !archive_mode
            && !from_objects && optind < argc
            && has_qo_extension(argv[optind])) {
        if (static_link) {
            fprintf(stderr,
                "error: .qo link mode does not support --static "
                "(output '%s'); link the generated host manually for static builds\n",
                output_path);
            return 1;
        }

        // All positional inputs must be .qo files.
        std::vector<std::string> object_paths;
        for (int i = optind; i < argc; ++i) {
            if (!has_qo_extension(argv[i])) {
                fprintf(stderr, "error: link-mode input '%s' must end "
                    "in .qo (mixing source files and .qo objects is not supported)\n", argv[i]);
                return 1;
            }
            char* resolved = realpath(argv[i], nullptr);
            if (resolved) {
                object_paths.emplace_back(resolved);
                free(resolved);
            } else {
                fprintf(stderr, "error: cannot resolve '%s': %s\n",
                    argv[i], strerror(errno));
                return 1;
            }
        }

        std::string glue_path = std::string(output_path) + ".main.cpp";
        return link_script_objects_to_executable(output_path, object_paths,
            glue_path, entry_fn, "link-mode");
    }

    // One-shot multi-source executable mode:
    //   qcc -o app src/lib.qr src/main.qr
    //
    // This is intentionally a thin composition of existing primitives:
    // batch-compile all sources into temporary `.qo` fragments with one
    // parse cycle, then link those fragments with the same link helper
    // used by explicit `.qo` link mode.
    if (!compile_only && !module_mode && !archive_mode && !from_objects
            && !context_dir && optind + 1 < argc
            && !has_qo_extension(argv[optind])) {
        if (!output_path) {
            fprintf(stderr,
                "error: multi-source executable mode requires -o/--output "
                "to name the output binary\n");
            return 1;
        }
        if (static_link) {
            fprintf(stderr,
                "error: multi-source executable mode does not support --static "
                "(output '%s'); link the generated host manually for static builds\n",
                output_path);
            return 1;
        }
        if (batch_output_dir) {
            fprintf(stderr,
                "error: --output-dir is only valid with -c/--compile-only; "
                "multi-source executable mode manages temporary objects internally\n");
            return 1;
        }
        if (!script_lib_dirs.empty()) {
            fprintf(stderr,
                "error: -L <dir> is per-file compile-only preload; "
                "multi-source executable mode parses all sources in one batch\n");
            return 1;
        }
        if (depfile_path) {
            fprintf(stderr,
                "error: --depfile is not supported in one-shot multi-source "
                "executable mode; use -c --output-dir for build-system integration\n");
            return 1;
        }
        if (depfile_dir) {
            fprintf(stderr,
                "error: --depfile-dir is not supported in one-shot multi-source "
                "executable mode; use -c --output-dir for build-system integration\n");
            return 1;
        }

        std::vector<std::string> target_files;
        target_files.reserve(argc - optind);
        for (int i = optind; i < argc; ++i) {
            if (has_qo_extension(argv[i])) {
                fprintf(stderr,
                    "error: multi-source executable mode does not allow mixed "
                    "source and .qo inputs; input '%s' is a .qo object\n",
                    argv[i]);
                return 1;
            }
            if (has_extension(argv[i], ".qm")) {
                fprintf(stderr,
                    "error: multi-source executable mode expects script/application "
                    "sources; input '%s' is a .qm module source\n", argv[i]);
                return 1;
            }
            if (has_extension(argv[i], ".qmod") || has_extension(argv[i], ".qoa")) {
                fprintf(stderr,
                    "error: multi-source executable mode expects source files; "
                    "input '%s' is a compiled artifact\n", argv[i]);
                return 1;
            }
            if (is_directory(argv[i])) {
                fprintf(stderr,
                    "error: multi-source executable mode does not accept directory "
                    "input '%s'; split modules require -m or --context workflows\n",
                    argv[i]);
                return 1;
            }
            target_files.emplace_back(argv[i]);
        }

        std::string temp_dir;
        std::string error;
        if (!make_qcc_temp_dir(temp_dir, error)) {
            fprintf(stderr,
                "error: multi-source executable setup failed for output '%s': %s\n",
                output_path, error.c_str());
            return 1;
        }

        qcc_init_qore();
        int compiled_count = 0;
        bool ok = QoreAOT::compileScriptFilesBatch(
            target_files, temp_dir, PO_DEFAULT, error,
            opt_level, target_triple, include_source,
            load_modules, stub_files, parse_defines,
            parse_option_flags, &compiled_count, false);
        qore_cleanup();
        if (!ok) {
            fprintf(stderr,
                "error: multi-source executable compile failed for output '%s' "
                "using temporary object directory '%s': %s\n",
                output_path, temp_dir.c_str(), error.c_str());
            if (save_temps) {
                fprintf(stderr, "qcc: temporary files saved in '%s'\n",
                    temp_dir.c_str());
            } else {
                cleanup_qcc_temp_dir(temp_dir);
            }
            return 1;
        }

        std::vector<std::string> object_paths;
        object_paths.reserve(target_files.size());
        for (const auto& source : target_files) {
            std::string object_path;
            if (!get_batch_object_path(source, temp_dir, object_path, error)) {
                fprintf(stderr,
                    "error: multi-source executable object collection failed "
                    "for output '%s' and source '%s': %s\n",
                    output_path, source.c_str(), error.c_str());
                if (save_temps) {
                    fprintf(stderr, "qcc: temporary files saved in '%s'\n",
                        temp_dir.c_str());
                } else {
                    cleanup_qcc_temp_dir(temp_dir);
                }
                return 1;
            }
            if (!is_file(object_path)) {
                fprintf(stderr,
                    "error: multi-source executable object collection failed "
                    "for output '%s': expected temporary object '%s' for "
                    "source '%s' was not generated\n",
                    output_path, object_path.c_str(), source.c_str());
                if (save_temps) {
                    fprintf(stderr, "qcc: temporary files saved in '%s'\n",
                        temp_dir.c_str());
                } else {
                    cleanup_qcc_temp_dir(temp_dir);
                }
                return 1;
            }
            object_paths.push_back(std::move(object_path));
        }

        std::string glue_path = join_path(temp_dir, "qcc-main.cpp");
        int rc = link_script_objects_to_executable(output_path, object_paths,
            glue_path, entry_fn, "multi-source executable", compiled_count,
            opt_level, include_source);
        if (save_temps) {
            fprintf(stderr, "qcc: temporary files saved in '%s'\n",
                temp_dir.c_str());
        } else {
            cleanup_qcc_temp_dir(temp_dir);
        }
        return rc;
    }

    // -a / --archive mode.  Same input shape as
    // --from-objects but produces a `.qoa` static archive instead of a
    // `.qmod`.  Must be checked before the --from-objects branch so
    // `-a -m` doesn't fall through to the .qmod aggregator.
    if (archive_mode) {
        if (from_objects) {
            fprintf(stderr,
                "error: -a/--archive and --from-objects are mutually exclusive\n");
            return 1;
        }
        if (!context_dir) {
            fprintf(stderr,
                "error: -a/--archive requires --context=DIR pointing at the "
                "split-module source directory\n");
            return 1;
        }
        if (!is_directory(context_dir)) {
            fprintf(stderr, "error: --context=%s is not a directory\n",
                context_dir);
            return 1;
        }
        if (optind >= argc) {
            fprintf(stderr,
                "error: -a/--archive requires at least one .qo input\n");
            return 1;
        }

        std::vector<std::string> object_paths;
        for (int i = optind; i < argc; ++i) {
            char* resolved = realpath(argv[i], nullptr);
            if (resolved) {
                object_paths.emplace_back(resolved);
                free(resolved);
            } else {
                object_paths.emplace_back(argv[i]);
            }
        }

        std::string output;
        if (output_path) {
            output = output_path;
        } else {
            std::string dir_str(context_dir);
            while (!dir_str.empty() && dir_str.back() == '/') {
                dir_str.pop_back();
            }
            size_t slash = dir_str.rfind('/');
            std::string basename = (slash != std::string::npos)
                ? dir_str.substr(slash + 1) : dir_str;
            output = basename + ".qoa";
        }

        qcc_init_qore();
        std::string error;
        bool ok = QoreAOT::archiveModuleFromObjects(
            context_dir, object_paths, output, PO_DEFAULT, error,
            opt_level, target_triple, include_source);
        if (!ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        if (qcc_output_verbose()) {
            printf("qcc: archived %zu .qo input%s into .qoa (-O%d%s): %s\n",
                object_paths.size(), object_paths.size() == 1 ? "" : "s",
                opt_level, source_mode_suffix(include_source), output.c_str());
        }
        qore_cleanup();
        return 0;
    }

    // --from-objects aggregator mode.  Takes a list of
    // per-file `.qo` inputs + --context=DIR (source dir) and produces a
    // `.qmod`.  All positional args are `.qo` files; validation happens
    // before we touch the standard single-file dispatch path.
    if (from_objects) {
        if (!module_mode) {
            fprintf(stderr,
                "error: --from-objects requires -m/--module\n");
            return 1;
        }
        if (!context_dir) {
            fprintf(stderr,
                "error: --from-objects requires --context=DIR pointing at "
                "the split-module source directory\n");
            return 1;
        }
        if (!is_directory(context_dir)) {
            fprintf(stderr, "error: --context=%s is not a directory\n",
                context_dir);
            return 1;
        }
        if (optind >= argc) {
            fprintf(stderr,
                "error: --from-objects requires at least one .qo input\n");
            return 1;
        }

        std::vector<std::string> object_paths;
        for (int i = optind; i < argc; ++i) {
            char* resolved = realpath(argv[i], nullptr);
            if (resolved) {
                object_paths.emplace_back(resolved);
                free(resolved);
            } else {
                object_paths.emplace_back(argv[i]);
            }
        }

        std::string output;
        if (output_path) {
            output = output_path;
        } else {
            // Derive from the context dir basename: "qlib/HttpServer/" -> "HttpServer.qmod"
            std::string dir_str(context_dir);
            while (!dir_str.empty() && dir_str.back() == '/') {
                dir_str.pop_back();
            }
            size_t slash = dir_str.rfind('/');
            std::string basename = (slash != std::string::npos)
                ? dir_str.substr(slash + 1) : dir_str;
            output = basename + ".qmod";
        }

        qcc_init_qore();
        std::string error;
        bool ok = QoreAOT::compileModuleFromObjects(
            context_dir, object_paths, output, PO_DEFAULT, error,
            opt_level, target_triple, include_source);
        if (!ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        if (qcc_output_verbose()) {
            printf("qcc: aggregated .qmod from %zu .qo input%s (-O%d%s): %s\n",
                object_paths.size(), object_paths.size() == 1 ? "" : "s",
                opt_level, source_mode_suffix(include_source), output.c_str());
        }
        // Aggregator mode re-parses every source in --context for
        // metadata extraction.  Per-.qo depfiles (emitted by the per-file
        // rule) cover the common case, but a new file added to the dir
        // without a matching `qcc -c` rule would be invisible without
        // this fallback.  Write empty-source + context depfile.
        if (depfile_path
                && !write_depfile(depfile_path, qcc_depfile_target(output),
                    std::string(), context_dir, nullptr, qcc_output_is_qmod(output))) {
            qore_cleanup();
            return 1;
        }
        qore_cleanup();
        return 0;
    }

    if (script_aggregate_symbol) {
        if (!compile_only) {
            fprintf(stderr,
                "error: --script-aggregate requires -c/--compile-only\n");
            return 1;
        }
        if (module_mode || archive_mode || from_objects || context_dir) {
            fprintf(stderr,
                "error: --script-aggregate is only valid for script-context "
                "compile mode\n");
            return 1;
        }
        if (!output_path) {
            fprintf(stderr,
                "error: --script-aggregate requires -o/--output for the "
                "aggregate object\n");
            return 1;
        }
        if (batch_output_dir) {
            fprintf(stderr,
                "error: --script-aggregate writes a single output; use -o "
                "instead of --output-dir\n");
            return 1;
        }
        if (!script_lib_dirs.empty()) {
            fprintf(stderr,
                "error: -L <dir> is per-file-compile only; "
                "--script-aggregate parses all sources in one program\n");
            return 1;
        }
        if (optind >= argc) {
            fprintf(stderr,
                "error: --script-aggregate requires at least one source file\n");
            return 1;
        }

        std::vector<std::string> target_files;
        target_files.reserve(argc - optind);
        for (int i = optind; i < argc; ++i) {
            if (has_qo_extension(argv[i]) || has_extension(argv[i], ".qmod")
                    || has_extension(argv[i], ".qoa")) {
                fprintf(stderr,
                    "error: --script-aggregate input '%s' must be a source "
                    "file, not a compiled artifact\n", argv[i]);
                return 1;
            }
            if (has_extension(argv[i], ".qm")) {
                fprintf(stderr,
                    "error: --script-aggregate expects script/application "
                    "sources; input '%s' is a .qm module source\n", argv[i]);
                return 1;
            }
            if (is_directory(argv[i])) {
                fprintf(stderr,
                    "error: --script-aggregate does not accept directory "
                    "input '%s'\n", argv[i]);
                return 1;
            }
            target_files.emplace_back(argv[i]);
        }

        QCCBuildManifest manifest;
        manifest.kind = "script-aggregate";
        manifest.output = output_path;
        manifest.index_json = write_index_json_path ? write_index_json_path : "";
        manifest.depfile = depfile_path ? depfile_path : "";
        manifest.aggregate_symbol = script_aggregate_symbol;
        manifest.inputs = target_files;
        capture_qcc_input_snapshots(manifest);
        QCCFileFingerprint output_before = qcc_file_fingerprint(manifest.output);
        if (skip_if_manifest_current && qcc_manifest_current(manifest, argv[0])) {
            if (qcc_output_verbose()) {
                printf("qcc: manifest current, skipped script aggregate .qo: %s\n", output_path);
            }
            std::string error;
            QCCFinishResult finish = finish_qcc_build(
                manifest, argv[0], output_before, false, true, false, error);
            if (finish != QCCFinishResult::Success) {
                fprintf(stderr, "error: %s\n", error.c_str());
                return qcc_finish_error_exit(finish);
            }
            return 0;
        }

        qcc_init_qore();
        std::string error;
        int compiled_count = 0;
        std::vector<std::string> dep_module_files;
        qore_aot_set_module_dep_sink(&dep_module_files);
        bool ok = QoreAOT::compileScriptAggregate(
            target_files, output_path, script_aggregate_symbol, PO_DEFAULT,
            error, opt_level, target_triple, include_source,
            load_modules, stub_files, parse_defines, parse_option_flags,
            &compiled_count, script_aggregate_native_registers);
        qore_aot_set_module_dep_sink(nullptr);
        if (!ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        std::sort(dep_module_files.begin(), dep_module_files.end());
        dep_module_files.erase(std::unique(dep_module_files.begin(),
            dep_module_files.end()), dep_module_files.end());
        if (!extend_qcc_input_snapshots(manifest, dep_module_files, error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        if (qcc_output_verbose()) {
            printf("qcc: compiled script aggregate .qo (-O%d, %s%s): %s\n",
                opt_level,
                script_aggregate_content_clause(script_aggregate_native_registers,
                    include_source, compiled_count).c_str(),
                source_mode_suffix(include_source), output_path);
        }
        std::vector<std::string> aggregate_dep_inputs = target_files;
        aggregate_dep_inputs.insert(aggregate_dep_inputs.end(),
            dep_module_files.begin(), dep_module_files.end());
        if (depfile_path && !write_depfile_list(depfile_path,
                qcc_depfile_target(output_path), aggregate_dep_inputs)) {
            qore_cleanup();
            return 1;
        }
        QCCFinishResult finish = finish_qcc_build(
            manifest, argv[0], output_before, true, false, false, error);
        if (finish != QCCFinishResult::Success) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return qcc_finish_error_exit(finish);
        }
        qore_cleanup();
        return 0;
    }

    // Get source file
    if (optind >= argc) {
        fprintf(stderr, "error: no source file specified\n");
        fprintf(stderr, "Try '%s --help' for more information.\n", argv[0]);
        return 1;
    }

    // Batch-compile mode.  When `-c` is used with
    // multiple positional source files (and no module-ish flag), parse
    // them into one QoreProgram (one parse cycle) and emit one `.qo`
    // per source into --output-dir.  Output names are derived from
    // canonical source paths to prevent same-basename sources in one
    // application from overwriting each other.  This avoids
    // compileScriptFile's O(N^2) sibling-preload cost when the build
    // system invokes qcc per-file.
    // Batch mode is also how a build compiles ONE source with the batch's
    // sidecar and depfile conventions: a shared parse over part of a group can
    // legitimately have a single member, and routing it through the per-file
    // path instead would reject the batch-only flags it was given.
    if (compile_only && !context_dir
            && (optind + 1 < argc
                || (batch_output_dir && optind < argc
                    && (batch_build_sidecars || depfile_dir)))) {
        if (!batch_output_dir) {
            fprintf(stderr, "error: multiple source files require "
                "--output-dir=<dir> (batch-compile mode)\n");
            return 1;
        }
        if (output_path) {
            fprintf(stderr, "error: -o <file> is single-output; use "
                "--output-dir=<dir> with multiple sources\n");
            return 1;
        }
        if (qcc_single_output_sidecars_requested()
                && !batch_script_aggregate_output) {
            fprintf(stderr,
                "error: qcc build sidecars are single-output only; use one qcc "
                "invocation per output, or request a fused batch script aggregate\n");
            return 1;
        }

        std::vector<std::string> batch_sources;
        for (int i = optind; i < argc; ++i) {
            batch_sources.emplace_back(argv[i]);
        }
        QoreAOTSourceSymbolManifest batch_source_symbols;
        const QoreAOTSourceSymbolManifest* batch_source_symbol_arg = nullptr;
        if (source_symbol_manifest_path) {
            std::string manifest_error;
            if (!read_source_symbol_manifest(source_symbol_manifest_path,
                    batch_source_symbols, manifest_error)) {
                fprintf(stderr, "error: %s\n", manifest_error.c_str());
                return 1;
            }
            if (!batch_source_symbols.empty()) {
                batch_source_symbol_arg = &batch_source_symbols;
            }
        }
        QCCBuildManifest batch_input_manifest;
        batch_input_manifest.output = batch_script_aggregate_output
            ? batch_script_aggregate_output : batch_output_dir;
        batch_input_manifest.inputs = batch_sources;
        batch_input_manifest.extra_inputs = batch_script_aggregate_manifest_inputs;
        capture_qcc_input_snapshots(batch_input_manifest);
        std::string error;
        if (!qcc_test_wait_after_input_snapshot(batch_input_manifest, error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            return 1;
        }
        if (verbose) {
            printf("Batch script-context .qo mode: %zu sources → %s\n",
                batch_sources.size(), batch_output_dir);
        }

        qcc_init_qore();
        std::string depfile_dir_arg;
        const std::string* depfile_dir_ptr = nullptr;
        if (depfile_dir) {
            depfile_dir_arg = depfile_dir;
            depfile_dir_ptr = &depfile_dir_arg;
        }
        std::vector<std::string> batch_objects;
        std::vector<QCCFileFingerprint> batch_output_before;
        std::vector<std::string> published_success_stamps;
        QCCFileFingerprint aggregate_output_before;
        if (batch_script_aggregate_output) {
            aggregate_output_before = qcc_file_fingerprint(
                batch_script_aggregate_output);
        }
        if (batch_build_sidecars) {
            batch_objects.reserve(batch_sources.size());
            batch_output_before.reserve(batch_sources.size());
            for (size_t i = 0; i < batch_sources.size(); ++i) {
                if (i && !(i % 100)
                        && qcc_check_cancel("qcc batch sidecar input collection")) {
                    fprintf(stderr, "error: cancelled during batch sidecar input collection\n");
                    qore_cleanup();
                    return 1;
                }
                const std::string& source = batch_sources[i];
                std::string object;
                if (!get_batch_object_path(source, batch_output_dir, object, error)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                batch_output_before.push_back(qcc_file_fingerprint(object));
                batch_objects.push_back(std::move(object));
            }
        }
        int aggregate_compiled_count = 0;
        std::string aggregate_output_arg = batch_script_aggregate_output
            ? batch_script_aggregate_output : "";
        std::string aggregate_symbol_arg = batch_script_aggregate_symbol
            ? batch_script_aggregate_symbol : "";
        std::vector<QoreAOTSourceFingerprint> observed_source_fingerprints;
        std::vector<std::string> dep_module_files;
        qore_aot_set_module_dep_sink(&dep_module_files);
        bool ok = QoreAOT::compileScriptFilesBatch(
            batch_sources, batch_output_dir, PO_DEFAULT, error,
            opt_level, target_triple, include_source,
            load_modules, stub_files, parse_defines,
            parse_option_flags, nullptr, true, depfile_dir_ptr,
            batch_build_sidecars,
            batch_script_aggregate_output ? &aggregate_output_arg : nullptr,
            batch_script_aggregate_symbol ? &aggregate_symbol_arg : nullptr,
            script_aggregate_native_registers,
            batch_script_aggregate_output ? &aggregate_compiled_count : nullptr,
            &observed_source_fingerprints,
            // A batch over PART of a group resolves its remaining cross-member
            // references against these; a whole-group batch is given none,
            // because every declaration it needs is in the same parse.
            script_lib_dirs,
            // And it needs to know which source provides each symbol, for the
            // same reason the per-file path does: a declaration this parse makes
            // can also arrive through a sibling's object.
            batch_source_symbol_arg);
        qore_aot_set_module_dep_sink(nullptr);
        if (!ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            int batch_rc = QoreAOT::lastCompileFailedInPreload() ? QCC_EXIT_PRELOAD_FAILED : 1;
            qore_cleanup();
            return batch_rc;
        }
        std::sort(dep_module_files.begin(), dep_module_files.end());
        dep_module_files.erase(std::unique(dep_module_files.begin(),
            dep_module_files.end()), dep_module_files.end());
        if (!extend_qcc_input_snapshots(batch_input_manifest,
                dep_module_files, error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        if (depfile_path) {
            if (!write_depfile_list(depfile_path,
                    qcc_depfile_target(batch_input_manifest.output),
                    dep_module_files)
                    || !rewrite_depfile_source_content_stamps(depfile_path,
                        qcc_depfile_target(batch_input_manifest.output), error)) {
                if (!error.empty()) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                }
                qore_cleanup();
                return 1;
            }
        }
        if (!capture_qcc_observed_source_snapshots(batch_input_manifest,
                observed_source_fingerprints, error)) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return 1;
        }
        QCCFinishResult input_result = validate_qcc_input_snapshots(
            batch_input_manifest, error);
        if (input_result != QCCFinishResult::Success) {
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return qcc_finish_error_exit(input_result);
        }
        if (batch_build_sidecars) {
            const char* aggregate_index_path = write_index_json_path;
            const char* aggregate_manifest_path = write_manifest_path;
            const char* aggregate_status_path = write_status_json_path;
            const char* aggregate_success_stamp_path = success_stamp_path;
            const char* aggregate_content_stamp_path = content_stamp_path;
            const char* aggregate_compile_contract_stamp_path =
                compile_contract_stamp_path;
            const char* saved_aggregate_contract_stamp_path =
                aggregate_contract_stamp_path;
            const char* saved_declaration_contract_stamp_path =
                declaration_contract_stamp_path;
            for (size_t i = 0; i < batch_objects.size(); ++i) {
                if (i && !(i % 100)
                        && qcc_check_cancel(
                            "qcc batch compile-contract sidecar emission")) {
                    fprintf(stderr, "error: cancelled during batch compile-contract sidecar emission\n");
                    qore_cleanup();
                    return 1;
                }
                std::string contract_stamp = batch_objects[i]
                    + ".compile-contract.stamp";
                if (!write_aot_compile_contract_stamp_file(
                        contract_stamp.c_str(), batch_objects[i].c_str(),
                        error)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                // The declaration contract has to exist before ANY member's depfile is
                // rewritten, for the same reason the compile contract does: the rewrite that
                // narrows a folded-value dependency to a provider's declaration contract can
                // only narrow to a stamp that is on disk, and the batch emits its members in
                // parallel.  Writing it per member as the sidecar loop reaches it would let a
                // consumer narrow or not narrow according to whether the provider happened to
                // be earlier in the batch -- or, on a clean tree, according to nothing at all.
                if (depfile_declaration_contract_stamps) {
                    std::string aggregate_stamp = batch_objects[i]
                        + ".aggregate-contract.stamp";
                    if (!write_aot_aggregate_contract_stamp_file(
                            aggregate_stamp.c_str(), batch_objects[i].c_str(),
                            error)) {
                        fprintf(stderr, "error: %s\n", error.c_str());
                        qore_cleanup();
                        return 1;
                    }
                    std::string declaration_stamp = batch_objects[i]
                        + ".declaration-contract.stamp";
                    if (!write_aot_declaration_contract_stamp_file(
                            declaration_stamp.c_str(), batch_objects[i].c_str(),
                            error)) {
                        fprintf(stderr, "error: %s\n", error.c_str());
                        qore_cleanup();
                        return 1;
                    }
                    // Same reason, same pass: a consumer can only record a
                    // provider's body contract as a dependency once the provider
                    // has published one.
                    std::string body_stamp = batch_objects[i]
                        + ".body-contract.stamp";
                    if (!write_aot_body_contract_stamp_file(
                            body_stamp.c_str(), batch_objects[i].c_str(),
                            error)) {
                        fprintf(stderr, "error: %s\n", error.c_str());
                        qore_cleanup();
                        return 1;
                    }
                }
            }
            AOTCompileContractProviderMap batch_contract_providers;
            if (!build_aot_compile_contract_provider_map(batch_objects,
                    batch_contract_providers, error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                qore_cleanup();
                return 1;
            }
            for (size_t i = 0; i < batch_objects.size(); ++i) {
                if (i && !(i % 100)
                        && qcc_check_cancel("qcc batch sidecar emission")) {
                    fprintf(stderr, "error: cancelled during batch sidecar emission\n");
                    qore_cleanup();
                    return 1;
                }
                const std::string& object = batch_objects[i];
                std::string index = object + ".idx.json";
                std::string manifest_path = object + ".source.manifest.json";
                std::string status = object + ".status.json";
                std::string stamp = object + ".stamp";
                std::string content_stamp = object + ".content.stamp";
                std::string compile_contract_stamp = object
                    + ".compile-contract.stamp";
                std::string aggregate_contract_stamp = object
                    + ".aggregate-contract.stamp";
                std::string declaration_contract_stamp = object
                    + ".declaration-contract.stamp";
                size_t slash = object.find_last_of("/\\");
                std::string object_basename = slash == std::string::npos
                    ? object : object.substr(slash + 1);
                std::string depfile = depfile_dir_arg + "/" + object_basename + ".d";

                write_index_json_path = index.c_str();
                write_manifest_path = manifest_path.c_str();
                write_status_json_path = status.c_str();
                success_stamp_path = stamp.c_str();
                content_stamp_path = content_stamp.c_str();
                compile_contract_stamp_path =
                    compile_contract_stamp.c_str();
                aggregate_contract_stamp_path =
                    aggregate_contract_stamp.c_str();
                declaration_contract_stamp_path =
                    declaration_contract_stamp.c_str();

                if (!add_aot_import_provider_depfile_inputs(object, depfile,
                        object + ".stamp", error)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                if (!rewrite_aot_compile_contract_depfile(object,
                        {batch_output_dir}, depfile, object + ".stamp",
                        error, &batch_contract_providers)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                if (!rewrite_aot_declaration_contract_depfile(object,
                        {batch_output_dir}, depfile, object + ".stamp",
                        error, &batch_contract_providers)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                if (!add_aot_body_contract_depfile_inputs(object,
                        {batch_output_dir}, depfile, object + ".stamp",
                        error, &batch_contract_providers)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                if (!write_aot_load_requires(object, error)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                if (!rewrite_depfile_source_content_stamps(depfile,
                        object + ".stamp", error)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }

                QCCBuildManifest manifest;
                manifest.kind = "script-file";
                manifest.output = object;
                manifest.index_json = index;
                manifest.depfile = depfile;
                manifest.inputs.push_back(batch_sources[i]);
                manifest.input_snapshots = batch_input_manifest.input_snapshots;
                manifest.observed_source_snapshots =
                    batch_input_manifest.observed_source_snapshots;
                if (!add_aot_compile_contract_depfile_inputs(depfile,
                        manifest.extra_inputs, error)) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return 1;
                }
                QCCFinishResult finish = finish_qcc_build(
                    manifest, argv[0], batch_output_before[i],
                    true, false, false, error, false);
                if (finish != QCCFinishResult::Success) {
                    fprintf(stderr, "error: %s\n", error.c_str());
                    qore_cleanup();
                    return qcc_finish_error_exit(finish);
                }
                published_success_stamps.push_back(stamp);
            }
            write_index_json_path = aggregate_index_path;
            write_manifest_path = aggregate_manifest_path;
            write_status_json_path = aggregate_status_path;
            success_stamp_path = aggregate_success_stamp_path;
            content_stamp_path = aggregate_content_stamp_path;
            compile_contract_stamp_path = aggregate_compile_contract_stamp_path;
            aggregate_contract_stamp_path =
                saved_aggregate_contract_stamp_path;
            declaration_contract_stamp_path =
                saved_declaration_contract_stamp_path;
        }
        if (batch_script_aggregate_output) {
            QCCBuildManifest manifest;
            manifest.kind = "script-aggregate";
            manifest.output = batch_script_aggregate_output;
            manifest.index_json = write_index_json_path
                ? write_index_json_path : "";
            manifest.depfile = depfile_path ? depfile_path : "";
            manifest.aggregate_symbol = batch_script_aggregate_symbol;
            manifest.inputs = batch_sources;
            manifest.extra_inputs = batch_script_aggregate_manifest_inputs;
            manifest.include_command_manifest_inputs = false;
            manifest.input_snapshots = batch_input_manifest.input_snapshots;
            QCCFinishResult finish = finish_qcc_build(
                manifest, argv[0], aggregate_output_before,
                true, false, false, error, false);
            if (finish != QCCFinishResult::Success) {
                fprintf(stderr, "error: %s\n", error.c_str());
                qore_cleanup();
                return qcc_finish_error_exit(finish);
            }
            if (success_stamp_path) {
                published_success_stamps.emplace_back(success_stamp_path);
            }
            if (qcc_output_verbose()) {
                printf("qcc: compiled fused script aggregate .qo (-O%d, %s%s): %s\n",
                    opt_level,
                    script_aggregate_content_clause(script_aggregate_native_registers,
                        include_source, aggregate_compiled_count).c_str(),
                    source_mode_suffix(include_source),
                    batch_script_aggregate_output);
            }
        }
        input_result = validate_qcc_input_snapshots(batch_input_manifest, error);
        if (input_result != QCCFinishResult::Success) {
            std::string cleanup_error;
            for (const std::string& stamp : published_success_stamps) {
                std::string stamp_error;
                if (!remove_qcc_file_if_exists(stamp, stamp_error)
                        && cleanup_error.empty()) {
                    cleanup_error = std::move(stamp_error);
                }
            }
            if (!cleanup_error.empty()) {
                error += "; additionally, " + cleanup_error;
                input_result = QCCFinishResult::Error;
            }
            fprintf(stderr, "error: %s\n", error.c_str());
            qore_cleanup();
            return qcc_finish_error_exit(input_result);
        }
        qore_cleanup();
        return 0;
    }

    const char* source_file = argv[optind];

    if (depfile_dir) {
        fprintf(stderr,
            "error: --depfile-dir is only valid with batch -c --output-dir "
            "mode and multiple source files\n");
        return 1;
    }

    // Resolve to absolute path so compiled executables can resolve relative %requires
    // paths even when run from a different working directory
    std::string abs_source_file;
    {
        char* resolved = realpath(source_file, nullptr);
        if (resolved) {
            abs_source_file = resolved;
            free(resolved);
            source_file = abs_source_file.c_str();
        }
    }

    // Check for multiple source files (not supported)
    if (optind + 1 < argc) {
        fprintf(stderr, "error: multiple source files not supported (got '%s' after '%s')\n",
            argv[optind + 1], source_file);
        return 1;
    }

    // Check if input is a directory (split module)
    bool is_split_module = is_directory(source_file);

    // Script-context mode.  When `-c` is used and
    // the input is neither a `.qm` nor a directory AND no
    // `--context=DIR` is supplied, compile as a plain script file.
    // Optional `-L <dir>` inputs preload sibling `.qo` decls so
    // cross-file refs resolve at parse time.
    bool script_mode = false;
    if (compile_only && !context_dir && !is_split_module) {
        size_t len = strlen(source_file);
        bool is_qm = (len > 3 && strcmp(source_file + len - 3, ".qm") == 0);
        if (!is_qm) {
            script_mode = true;
            if (verbose) {
                printf("Script-context .qo mode (target=%s, %zu -L paths)\n",
                    source_file, script_lib_dirs.size());
            }
        }
    }

    // --context=DIR opts the caller into per-file .qo
    // compilation. The input must be a single file in that directory
    // (either the module's `.qm` or one of its `.qc`/`.ql` components);
    // the directory is the parse context, not the input.
    bool per_file_mode = (context_dir != nullptr);
    if (per_file_mode) {
        if (!compile_only) {
            fprintf(stderr, "error: --context=DIR requires -c/--compile-only\n");
            return 1;
        }
        if (is_split_module) {
            fprintf(stderr, "error: --context=DIR is incompatible with a directory input; "
                    "pass a single .qm/.qc/.ql file from the directory instead\n");
            return 1;
        }
        if (!is_directory(context_dir)) {
            fprintf(stderr, "error: --context=%s is not a directory\n", context_dir);
            return 1;
        }
        module_mode = true;  // always module-shaped in per-file mode
        if (verbose) {
            printf("Per-file .qo mode: context=%s\n", context_dir);
        }
    }

    // Auto-detect module mode from extension or directory
    if (!module_mode) {
        if (is_split_module) {
            module_mode = true;
            if (verbose) {
                printf("Auto-detected split module mode from directory input\n");
            }
        } else {
            size_t len = strlen(source_file);
            if (len > 3 && strcmp(source_file + len - 3, ".qm") == 0) {
                module_mode = true;
                if (verbose) {
                    printf("Auto-detected module mode from .qm extension\n");
                }
            }
        }
    }

    // Warn about ignored options
    if (static_link && module_mode) {
        fprintf(stderr, "warning: --static is ignored when compiling modules\n");
        if (warnings_are_errors) {
            return 1;
        }
    }

    // -c (compile-only) applies to module inputs (.qm / split
    // dir / per-file fragment thereof) and also to
    // plain script files (any non-.qm source, including .qr/.q/.qc/.ql).
    // Only reject
    // the combination if we're in neither mode.
    if (compile_only && !module_mode && !script_mode) {
        fprintf(stderr, "error: -c/--compile-only requires either a module "
                "input (.qm / split-module dir / .qc fragment with --context), "
                "or a script-mode source file (.qr/.q/.qc/.ql or another non-.qm "
                "source with optional -L<dir> "
                "preload paths)\n");
        return 1;
    }

    // -L is meaningful only in script-context compile.
    if (!script_lib_dirs.empty() && !script_mode) {
        fprintf(stderr, "error: -L <dir> is only meaningful with script-mode "
                "compile (-c on a .qr/.q/.qc/.ql or another non-.qm source)\n");
        return 1;
    }

    // Reject `-o` mixed with `--output-dir` for
    // single-file compile (same rule as batch mode above).  They are
    // mutually exclusive output-naming strategies.
    if (output_path && batch_output_dir) {
        fprintf(stderr, "error: -o <file> and --output-dir=<dir> are "
                "mutually exclusive\n");
        return 1;
    }

    // Determine output path
    std::string output;
    if (output_path) {
        output = output_path;
    } else {
        if (is_split_module) {
            // For split modules, derive output from directory basename
            std::string dir_str(source_file);
            // Remove trailing slashes
            while (!dir_str.empty() && dir_str.back() == '/') {
                dir_str.pop_back();
            }
            // Extract basename
            size_t last_slash = dir_str.rfind('/');
            std::string basename = (last_slash != std::string::npos)
                ? dir_str.substr(last_slash + 1)
                : dir_str;
            output = basename + (compile_only ? ".qo" : ".qmod");
        } else if (per_file_mode) {
            // Per-file split-module compile (`--context=DIR`).
            // Preserve the source extension in the output name so primary
            // (`.qm`) and secondary (`.qc` / `.ql`) files that share a
            // basename don't collide — e.g. `DataProvider.qm → DataProvider.qm.qo`
            // and `DataProvider.qc → DataProvider.qc.qo`.  Mirrors the
            // symbol-mangling change in `compileSeparatedModuleFile`
            // that uses the full basename (extension included) for
            // `qore_<sanmod>_<sanfile>_*` symbols.
            std::string basename(source_file);
            size_t slash = basename.rfind('/');
            if (slash != std::string::npos) {
                basename = basename.substr(slash + 1);
            }
            output = basename + ".qo";
        } else {
            // Script-mode / single-file default: strip extension and
            // append `.qo` (e.g. `foo.qr → foo.qo`).  Script mode has no
            // primary/secondary split so there's no collision risk.
            output = get_default_output(source_file, module_mode, compile_only);
        }
        // Honor `--output-dir=DIR` for single-file
        // compile too (previously only applied to batch mode on ≥2
        // positional sources, making single-file builds silently write
        // `.qo`s to the current directory).  CMake build systems need
        // a consistent output location regardless of source count.
        if (batch_output_dir) {
            std::string dir_str(batch_output_dir);
            while (!dir_str.empty() && dir_str.back() == '/') {
                dir_str.pop_back();
            }
            output = dir_str + "/" + output;
        }
    }

    // For split modules, skip reading source file (compileSeparatedModule handles it)
    std::string source_text;
    if (!is_split_module) {
        if (!read_file(source_file, source_text)) {
            return 1;
        }
    }

    // Allow environment variable to override optimization level for debugging/testing
    QoreEnvironmentValue opt_override_holder("QORE_AOT_OPT_LEVEL");
    const char* opt_override = opt_override_holder.c_str();
    if (opt_override) {
        opt_level = atoi(opt_override);
    }

    if (verbose) {
        if (is_split_module) {
            printf("Source: %s (split module directory)\n", source_file);
        } else {
            printf("Source: %s (%zu bytes)\n", source_file, source_text.size());
        }
        printf("Output: %s\n", output.c_str());
        printf("Mode: %s\n", is_split_module ? "split module" : (module_mode ? "module" : "executable"));
        printf("Optimization: -O%d\n", opt_level);
        if (static_link) {
            printf("Static linking: enabled\n");
        }
        if (target_triple) {
            printf("Target: %s\n", target_triple);
        }
    }

    std::string error;
    QCCBuildManifest manifest;
    manifest.output = output;
    manifest.index_json = write_index_json_path ? write_index_json_path : "";
    manifest.depfile = depfile_path ? depfile_path : "";
    if (script_mode) {
        manifest.kind = "script-file";
        manifest.inputs.push_back(source_file);
        if (!manifest_skip_qo_library_inputs) {
            collect_qo_library_inputs(manifest.extra_inputs, script_lib_dirs, output);
        }
    } else if (per_file_mode) {
        manifest.kind = "module-file";
        manifest.inputs.push_back(source_file);
        if (context_dir) {
            manifest.extra_inputs.push_back(context_dir);
        }
    } else if (is_split_module) {
        manifest.kind = compile_only ? "split-module-qo" : "split-module";
        manifest.inputs.push_back(source_file);
    } else if (module_mode) {
        manifest.kind = compile_only ? "module-qo" : "module";
        manifest.inputs.push_back(source_file);
    } else {
        manifest.kind = "executable";
        manifest.inputs.push_back(source_file);
    }
    if (depfile_path
            && !add_aot_compile_contract_depfile_inputs(depfile_path,
                manifest.extra_inputs, error)) {
        fprintf(stderr, "error: %s\n", error.c_str());
        return 1;
    }
    if (is_split_module) {
        capture_qcc_input_snapshots(manifest);
    } else {
        QCCFileFingerprint source_fingerprint = qcc_content_fingerprint(source_text);
        std::string source_path = source_file;
        capture_qcc_input_snapshots(manifest, &source_path, &source_fingerprint);
    }
    QCCFileFingerprint output_before = qcc_file_fingerprint(manifest.output);
    if (skip_if_manifest_current && qcc_manifest_current(manifest, argv[0])) {
        if (qcc_output_verbose()) {
            printf("qcc: manifest current, skipped %s: %s\n",
                manifest.kind.c_str(), output.c_str());
        }
        std::string error;
        QCCFinishResult finish = finish_qcc_build(
            manifest, argv[0], output_before, false, true, false, error);
        if (finish != QCCFinishResult::Success) {
            fprintf(stderr, "error: %s\n", error.c_str());
            return qcc_finish_error_exit(finish);
        }
        return 0;
    }
    if (!qcc_test_wait_after_input_snapshot(manifest, error)) {
        fprintf(stderr, "error: %s\n", error.c_str());
        return 1;
    }

    // Initialize Qore library
    qcc_init_qore();

    int rc = 0;
    QoreParseOptions compile_po = PO_DEFAULT;
    if (!apply_parse_option_flags(compile_po, error)) {
        fprintf(stderr, "error: %s\n", error.c_str());
        qore_cleanup();
        return 1;
    }

    if (script_mode) {
        // Compile a single script-style source with
        // optional sibling-.qo decl preload.
        std::vector<std::string> parsed_files;
        QoreAOTSourceSymbolManifest source_symbols;
        const QoreAOTSourceSymbolManifest* source_symbol_arg = nullptr;
        std::vector<QoreAOTSourceFingerprint> observed_source_fingerprints;
        if (source_symbol_manifest_path) {
            if (!read_source_symbol_manifest(source_symbol_manifest_path, source_symbols, error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                qore_cleanup();
                return 1;
            }
            if (!source_symbols.empty()) {
                source_symbol_arg = &source_symbols;
            }
        }
        std::vector<std::string> dep_module_files;
        qore_aot_set_module_dep_sink(&dep_module_files);
        bool script_ok = QoreAOT::compileScriptFile(
                source_file,
                script_lib_dirs,
                output,
                compile_po,
                error,
                opt_level,
                target_triple,
                include_source,
                load_modules,
                stub_files,
                parse_defines,
                depfile_path ? &parsed_files : nullptr,
                source_symbol_arg,
                &observed_source_fingerprints);
        qore_aot_set_module_dep_sink(nullptr);
        if (!script_ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            rc = QoreAOT::lastCompileFailedInPreload() ? QCC_EXIT_PRELOAD_FAILED : 1;
        } else {
            std::sort(dep_module_files.begin(), dep_module_files.end());
            dep_module_files.erase(std::unique(dep_module_files.begin(),
                dep_module_files.end()), dep_module_files.end());
            parsed_files.insert(parsed_files.end(), dep_module_files.begin(),
                dep_module_files.end());
            std::sort(parsed_files.begin(), parsed_files.end());
            parsed_files.erase(std::unique(parsed_files.begin(),
                parsed_files.end()), parsed_files.end());
            if (!extend_qcc_input_snapshots(manifest,
                    dep_module_files, error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (!capture_qcc_observed_source_snapshots(manifest,
                    observed_source_fingerprints, error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (qcc_output_verbose()) {
                printf("qcc: compiled script-context .qo (-O%d, %zu -L path%s%s): %s\n",
                    opt_level, script_lib_dirs.size(),
                    script_lib_dirs.size() == 1 ? "" : "s",
                    source_mode_suffix(include_source), output.c_str());
            }
            // deps = the target source plus its `%include` closure, as
            // reported by compileScriptFile (the same set it used to filter
            // the `-L` preload).  This lets the build rebuild the `.qo` when
            // any `%include`d file changes — not just the target itself.
            if (!rc && depfile_path && !write_depfile_list(depfile_path,
                    qcc_depfile_target(output), parsed_files)) {
                rc = 1;
            } else if (!rc && depfile_path
                    && !add_aot_import_provider_depfile_inputs(output,
                        depfile_path, qcc_depfile_target(output), error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (!rc && depfile_path
                    && !rewrite_aot_compile_contract_depfile(output,
                        script_lib_dirs, depfile_path,
                        qcc_depfile_target(output), error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (!rc && depfile_path
                    && !rewrite_aot_declaration_contract_depfile(output,
                        script_lib_dirs, depfile_path,
                        qcc_depfile_target(output), error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (!rc && depfile_path
                    && !add_aot_body_contract_depfile_inputs(output,
                        script_lib_dirs, depfile_path,
                        qcc_depfile_target(output), error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (!rc && depfile_path && !write_aot_load_requires(output, error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (!rc && depfile_path
                    && !rewrite_depfile_source_content_stamps(depfile_path,
                        qcc_depfile_target(output), error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else if (!rc && depfile_path
                    && !add_aot_compile_contract_depfile_inputs(depfile_path,
                        manifest.extra_inputs, error)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            }
        }
    } else if (per_file_mode) {
        // Compile a single file from a split module
        // directory.  The directory is the parse context; the file is the
        // sole source of emitted metadata and native functions.
        std::vector<std::string> dep_module_files;
        qore_aot_set_module_dep_sink(&dep_module_files);
        bool ok = QoreAOT::compileSeparatedModuleFile(
                context_dir,
                source_file,
                output,
                compile_po,
                error,
                opt_level,
                target_triple,
                include_source);
        qore_aot_set_module_dep_sink(nullptr);
        if (!ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            rc = 1;
        } else {
            if (qcc_output_verbose()) {
                printf("qcc: compiled per-file .qo (-O%d%s): %s\n", opt_level,
                    source_mode_suffix(include_source), output.c_str());
            }
            // deps = the source context plus dependency modules in the selected form.
            std::vector<std::string> module_deps =
                qcc_module_depfile_inputs(dep_module_files);
            if (depfile_path
                    && !write_depfile(depfile_path, qcc_depfile_target(output),
                                      source_file, context_dir,
                                      &module_deps, qcc_output_is_qmod(output))) {
                rc = 1;
            }
        }
    } else if (is_split_module) {
        // Compile split module directory; the depfile of a .qmod lists everything the module depends on
        std::vector<std::string> dep_module_files;
        qcc_set_module_dep_sink(&dep_module_files, output);
        bool ok = QoreAOT::compileSeparatedModule(
                source_file,
                output,
                compile_po,
                error,
                opt_level,
                target_triple,
                include_source,
                compile_only);
        qore_aot_set_module_dep_sink(nullptr);
        if (!ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            rc = 1;
        } else {
            if (qcc_output_verbose()) {
                printf("qcc: compiled split module (-O%d%s%s): %s\n", opt_level,
                    compile_only ? ", relocatable .qo" : "",
                    source_mode_suffix(include_source), output.c_str());
            }
            // source_file is the split-module directory itself;
            // pass it as `context` so every .qm/.qc/.ql inside counts as a dep.
            // Leave `source` empty so the target dir is not double-listed.
            // Dependency modules use the selected deterministic depfile form.
            std::vector<std::string> module_deps =
                qcc_module_depfile_inputs(dep_module_files, qcc_output_is_qmod(output));
            if (depfile_path
                    && !write_depfile(depfile_path, qcc_depfile_target(output),
                                      std::string(), source_file,
                                      &module_deps, qcc_output_is_qmod(output))) {
                rc = 1;
            }
        }
    } else if (module_mode) {
        // Compile single-file module; the depfile of a .qmod lists everything the module depends on
        std::vector<std::string> dep_module_files;
        qcc_set_module_dep_sink(&dep_module_files, output);
        bool ok = QoreAOT::compileModule(
                source_text.c_str(), (int)source_text.size(),
                source_file,
                output,
                compile_po,
                error,
                opt_level,
                target_triple,
                include_source,
                compile_only);
        qore_aot_set_module_dep_sink(nullptr);
        if (!ok) {
            fprintf(stderr, "error: %s\n", error.c_str());
            rc = 1;
        } else {
            if (qcc_output_verbose()) {
                printf("qcc: compiled module (-O%d%s%s): %s\n", opt_level,
                    compile_only ? ", relocatable .qo" : "",
                    source_mode_suffix(include_source), output.c_str());
            }
            // deps = the .qm file plus dependency modules in the selected form.
            std::vector<std::string> module_deps =
                qcc_module_depfile_inputs(dep_module_files, qcc_output_is_qmod(output));
            if (depfile_path && !write_depfile(depfile_path, qcc_depfile_target(output),
                                               source_file, nullptr,
                                               &module_deps, qcc_output_is_qmod(output))) {
                rc = 1;
            }
        }
    } else {
        // Create the Program and parse with the options the interpreter uses: the script's own parse
        // directives, %modern for every extension but ".q" (see QoreProgram::parseFile()), and any --parse-option
        // flags; options are never forced, as that would silently change the script's parse semantics.
        // QoreAOT::compile() then rejects code that is not %modern (see qore_parse_options_support_ir()).
        QoreProgram* qpgm = new QoreProgram(compile_po);
        ExceptionSink xsink;
        ExceptionSink wsink;

        qpgm->parseFile(source_file, &xsink, &wsink, QP_WARN_DEFAULT);

        if (xsink.isException()) {
            xsink.handleExceptions();
            rc = 1;
        } else if (qccHandleWarnings(wsink)) {
            rc = 1;
        } else {
            // Compile to executable
            QoreParseOptions po = qpgm->getParseOptions() | compile_po;
            if (!QoreAOT::compile(
                    qpgm,
                    source_text.c_str(), (int)source_text.size(),
                    source_file,
                    output,
                    po,
                    error,
                    opt_level,
                    target_triple,
                    static_link,
                    include_source)) {
                fprintf(stderr, "error: %s\n", error.c_str());
                rc = 1;
            } else {
                if (qcc_output_verbose()) {
                    printf("qcc: compiled executable (-O%d%s%s): %s\n", opt_level,
                        static_link ? ", static" : "",
                        source_mode_suffix(include_source), output.c_str());
                }
            }
        }

        qpgm->waitForTerminationAndDeref(&xsink);
    }

    if (!rc) {
        QCCFinishResult finish = finish_qcc_build(
            manifest, argv[0], output_before, true, false, false, error);
        if (finish != QCCFinishResult::Success) {
            fprintf(stderr, "error: %s\n", error.c_str());
            rc = qcc_finish_error_exit(finish);
        }
    }

    // Cleanup
    qore_cleanup();

    return rc;
}