wowdump 0.2.1 → 0.3.2

package/dist/wow-analysis.js

@@ -1,1430 +0,0 @@
-import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
-import { brokerManagedCommand } from "./frida-runtime.js";
-import { BuildBundleStore } from "./build-bundle-loader.js";
-export const WOW_ANALYSIS_BUILD_KEY = "retail@12.0.7.68974";
-export const WOW_ANALYSIS_MODULE = "Wow.exe";
-export const WOW_IDA_IMAGE_BASE = "0x140000000";
-const REQUIRED_ARTIFACTS = [
-    { key: "luaAbi", role: "Lua ABI", file: suffix => `lua-abi-${suffix}.json`, json: true },
-    { key: "luaTrace", role: "Lua trace events", file: suffix => `lua-trace-${suffix}.jsonl`, json: false },
-    { key: "wrapperCoverage", role: "Lua wrapper coverage", file: suffix => `lua-wrapper-coverage-${suffix}.json`, json: true },
-    { key: "callgraph", role: "Lua wrapper call graph", file: suffix => `lua-wrapper-callgraph-${suffix}.json`, json: true },
-    { key: "clusters", role: "C++ implementation clusters", file: suffix => `cpp-implementation-clusters-${suffix}.json`, json: true },
-    { key: "dataSources", role: "C++ data sources", file: suffix => `cpp-data-sources-${suffix}.json`, json: true },
-    { key: "dataRootCoverage", role: "Data-root coverage", file: suffix => `data-root-coverage-${suffix}.json`, json: true },
-    { key: "buildProfile", role: "Build profile", file: suffix => `build-profile-${suffix}.json`, json: true },
-    { key: "readerVerification", role: "Reader verification", file: suffix => `data-reader-verification-${suffix}.json`, json: true },
-    { key: "nonLuaIndex", role: "Non-Lua system index", file: suffix => `non-lua-system-index-${suffix}.json`, json: true },
-    { key: "nonLuaCoverage", role: "Non-Lua system coverage", file: suffix => `non-lua-system-coverage-${suffix}.json`, json: true },
-    { key: "unresolved", role: "Unresolved ledger", file: suffix => `unresolved-ledger-${suffix}.json`, json: true },
-    { key: "process", role: "Process event log", file: suffix => `wow-analysis-process-${suffix}.jsonl`, json: false },
-    { key: "report", role: "Runtime analysis report", file: suffix => `WOW-runtime-analysis-${suffix}.md`, json: false },
-    { key: "manifest", role: "Analysis artifact manifest", file: suffix => `analysis-artifact-manifest-${suffix}.json`, json: true }
-];
-const DEFAULT_MAX_HOOKS = 64;
-// The default is intentionally small; an explicit caller may request the
-// complete indexed set (the agent still validates every target before attach).
-const MAX_LUA_HOOKS = 5130;
-const MAX_CPP_HOOKS = 5130;
-const MAX_EVENTS = 100_000;
-const MAX_READ_ITEMS = 10_000;
-const MAX_STRING_BYTES = 65_536;
-const MAX_SIGNATURE_CHECKS = 512;
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function stringValue(value) {
-    return typeof value === "string" && value.trim() !== "" ? value : undefined;
-}
-function integerValue(value) {
-    return typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
-}
-function booleanValue(value) {
-    return typeof value === "boolean" ? value : undefined;
-}
-function requiredString(value, field) {
-    const result = stringValue(value);
-    if (result === undefined)
-        throw new Error(`${field} is required`);
-    return result;
-}
-function boundedInteger(value, fallback, minimum, maximum, field) {
-    if (value === undefined)
-        return fallback;
-    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
-        throw new Error(`${field} must be an integer in [${minimum}, ${maximum}]`);
-    }
-    return value;
-}
-function boundedSampling(value) {
-    if (value === undefined)
-        return 1;
-    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1) {
-        throw new Error("sampling must be greater than 0 and at most 1");
-    }
-    return value;
-}
-function normalizeHex(value, field) {
-    if (typeof value === "number") {
-        if (!Number.isSafeInteger(value) || value < 0)
-            throw new Error(`${field} must be a non-negative RVA`);
-        return `0x${value.toString(16)}`;
-    }
-    const text = requiredString(value, field).trim();
-    if (!/^(?:0x)?[0-9a-f]+$/i.test(text))
-        throw new Error(`${field} must be hexadecimal`);
-    return `0x${BigInt(text.startsWith("0x") || text.startsWith("0X") ? text : `0x${text}`).toString(16)}`;
-}
-function hexToNumber(value, field) {
-    const normalized = normalizeHex(value, field);
-    const parsed = Number(BigInt(normalized));
-    if (!Number.isSafeInteger(parsed))
-        throw new Error(`${field} exceeds JavaScript's safe integer range`);
-    return parsed;
-}
-function hexAdd(base, offset) {
-    return `0x${(BigInt(base) + BigInt(typeof offset === "number" ? offset : normalizeHex(offset, "offset"))).toString(16)}`;
-}
-function buildSuffix(buildKey) {
-    const value = requiredString(buildKey, "buildKey");
-    const tail = value.split(".").at(-1)?.split("@").at(-1) ?? "";
-    if (!/^[A-Za-z0-9_-]+$/.test(tail))
-        throw new Error("buildKey has no safe artifact suffix");
-    return tail;
-}
-function flavorForBuild(buildKey) {
-    const prefix = buildKey.split("@", 1)[0];
-    return prefix && /^[A-Za-z0-9_-]+$/.test(prefix) ? prefix : undefined;
-}
-function arrayValue(value) {
-    return Array.isArray(value) ? value : [];
-}
-function recordsFrom(value, preferred = []) {
-    if (Array.isArray(value))
-        return value.filter(isRecord);
-    if (!isRecord(value))
-        return [];
-    for (const key of [...preferred, "records", "dataSources", "sources", "wrappers", "targets", "clusters", "systems", "items"]) {
-        const candidate = value[key];
-        if (Array.isArray(candidate))
-            return candidate.filter(isRecord);
-    }
-    return [];
-}
-function resultArray(result, key) {
-    const direct = result[key];
-    const value = direct ?? result.value;
-    return Array.isArray(value) ? value.filter(isRecord) : [];
-}
-function normalizeModuleName(value, fallback) {
-    return stringValue(value) ?? fallback;
-}
-function globExpression(pattern) {
-    if (pattern.length > 256)
-        throw new Error("glob exceeds 256 characters");
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
-    return new RegExp(`^${escaped}$`, "i");
-}
-function sha256(value) {
-    return createHash("sha256").update(value).digest("hex");
-}
-function pickPath(record, paths) {
-    for (const path of paths) {
-        let current = record;
-        for (const key of path) {
-            if (!isRecord(current)) {
-                current = undefined;
-                break;
-            }
-            current = current[key];
-        }
-        if (current !== undefined && current !== null)
-            return current;
-    }
-    return undefined;
-}
-function statusValue(record, ...keys) {
-    for (const key of keys) {
-        const value = stringValue(record[key]);
-        if (value !== undefined)
-            return value;
-    }
-    return undefined;
-}
-function summarizeRecord(record) {
-    const dataSourceId = stringValue(record.dataSourceId ?? record.id);
-    return {
-        ...(dataSourceId ? { dataSourceId } : {}),
-        ...(stringValue(record.name) ? { name: record.name } : {}),
-        ...(stringValue(record.system) ? { system: record.system } : {}),
-        ...(stringValue(record.buildKey) ? { buildKey: record.buildKey } : {}),
-        status: statusValue(record, "status", "resolutionStatus") ?? "unresolved",
-        readerStatus: statusValue(record, "readerStatus", "reader_status")
-            ?? (isRecord(record.reader) ? statusValue(record.reader, "status") : undefined)
-            ?? "unresolved",
-        ...(record.sourceApis !== undefined ? { sourceApis: record.sourceApis } : {}),
-        ...(record.sourceAPIs !== undefined ? { sourceAPIs: record.sourceAPIs } : {})
-    };
-}
-function normalizeApiList(input) {
-    const values = input.APIs ?? input.apis ?? [];
-    if (!Array.isArray(values) || values.length > 512)
-        throw new Error("APIs must contain at most 512 entries");
-    return values.map((value, index) => requiredString(value, `APIs[${index}]`));
-}
-function normalizeRvaSelection(value) {
-    if (value === undefined)
-        return [];
-    const values = Array.isArray(value) ? value : [value];
-    if (values.length > 512)
-        throw new Error("rva must contain at most 512 entries");
-    return values.map((item, index) => normalizeHex(item, `rva[${index}]`));
-}
-function requireSelection(input) {
-    if (normalizeApiList(input).length === 0
-        && input.namespace === undefined
-        && input.glob === undefined
-        && normalizeRvaSelection(input.rva).length === 0
-        && (!("clusterIds" in input) || !Array.isArray(input.clusterIds) || input.clusterIds.length === 0)
-        && input.all !== true) {
-        throw new Error("an explicit API, namespace, glob, RVA, cluster, or all=true selection is required");
-    }
-}
-const CPP_TRACE_SOURCE = String.raw `
-let catalog = null;
-let listeners = [];
-let events = [];
-let nextSeq = 1;
-let droppedEvents = 0;
-let active = false;
-let timer = null;
-let startedAt = null;
-let stoppedAt = null;
-let stopReason = null;
-const depthByThread = new Map();
-function emit(event, maxEvents) {
-  event.seq = nextSeq++;
-  if (events.length >= maxEvents) { events.shift(); droppedEvents++; }
-  events.push(event);
-}
-function stop(reason) {
-  const errors = [];
-  if (timer !== null) { clearTimeout(timer); timer = null; }
-  const detachedHooks = listeners.length;
-  for (const listener of listeners.splice(0)) {
-    try { listener.detach(); } catch (error) { errors.push(String(error)); }
-  }
-  depthByThread.clear();
-  active = false;
-  stoppedAt = new Date().toISOString();
-  stopReason = reason || 'requested';
-  return { ...status(), detachedHooks, detachErrors: errors };
-}
-function status() {
-  return {
-    active, buildKey: catalog && catalog.buildKey, moduleName: catalog && catalog.moduleName,
-    installedHooks: listeners.length, queuedEvents: events.length, droppedEvents,
-    startedAt, stoppedAt, stopReason
-  };
-}
-rpc.exports = {
-  configureCppTrace(value) {
-    stop('reconfigured');
-    catalog = value;
-    events = []; nextSeq = 1; droppedEvents = 0;
-    return { configured: true, buildKey: value.buildKey, targets: value.targets.length };
-  },
-  wowCppTraceStart(request) {
-    if (!catalog) throw new Error('C++ trace catalog is not configured');
-    if (active) throw new Error('C++ trace is already active');
-    if (request.buildKey !== catalog.buildKey) throw new Error('build mismatch');
-    if (request.pid !== undefined && request.pid !== Process.id) throw new Error('PID mismatch');
-    const module = Process.getModuleByName(catalog.moduleName);
-    const maxEvents = request.maxEvents;
-    const sampling = request.sampling;
-    const argumentCount = request.argumentCount;
-    for (const target of catalog.targets) {
-      const address = module.base.add(target.rvaNumber);
-      const range = Process.findRangeByAddress(address);
-      if (range === null || range.protection.indexOf('x') < 0) throw new Error('target is not executable: ' + target.id);
-      const listener = Interceptor.attach(address, {
-        onEnter(args) {
-          if (sampling < 1 && Math.random() > sampling) { this.__wowCppSkipped = true; return; }
-          const threadId = this.threadId;
-          const depth = (depthByThread.get(threadId) || 0) + 1;
-          depthByThread.set(threadId, depth);
-          this.__wowCppDepth = depth;
-          const captured = [];
-          if (request.captureArguments) {
-            for (let index = 0; index < argumentCount; index++) captured.push(args[index].toString());
-          }
-          emit({ type: 'cpp_trace_enter', timestamp: new Date().toISOString(), buildKey: catalog.buildKey,
-            moduleName: module.name, moduleBase: module.base.toString(), threadId, depth, target,
-            arguments: captured }, maxEvents);
-        },
-        onLeave(retval) {
-          if (this.__wowCppSkipped) return;
-          const threadId = this.threadId;
-          const depth = this.__wowCppDepth || depthByThread.get(threadId) || 1;
-          emit({ type: 'cpp_trace_leave', timestamp: new Date().toISOString(), buildKey: catalog.buildKey,
-            moduleName: module.name, moduleBase: module.base.toString(), threadId, depth, target,
-            returnValue: request.captureReturn ? retval.toString() : undefined }, maxEvents);
-          if (depth <= 1) depthByThread.delete(threadId); else depthByThread.set(threadId, depth - 1);
-        }
-      });
-      listeners.push(listener);
-    }
-    active = true; startedAt = new Date().toISOString(); stoppedAt = null; stopReason = null;
-    if (request.durationMs > 0) timer = setTimeout(() => stop('duration_elapsed'), request.durationMs);
-    return { ...status(), pid: Process.id, moduleBase: module.base.toString(), selectedTargets: catalog.targets.length };
-  },
-  wowCppTraceRead(afterSeq, limit) {
-    const selected = events.filter(event => event.seq > afterSeq).slice(0, limit);
-    return { events: selected, oldestSeq: events[0] ? events[0].seq : null,
-      newestSeq: events.length ? events[events.length - 1].seq : null,
-      nextAfterSeq: selected.length ? selected[selected.length - 1].seq : afterSeq, droppedEvents };
-  },
-  wowCppTraceStatus() { return status(); },
-  wowCppTraceStop(reason) { return stop(reason); },
-  dispose() { const result = stop('disposed'); catalog = null; return result; }
-};
-`;
-const DATA_READER_SOURCE = String.raw `
-function readable(address, size) {
-  const range = Process.findRangeByAddress(address);
-  if (range === null || range.protection.indexOf('r') < 0) throw new Error('unreadable address ' + address);
-  const end = address.add(size);
-  if (end.compare(range.base.add(range.size)) > 0) throw new Error('read crosses range at ' + address);
-}
-function readField(base, field, maxStringBytes) {
-  const address = base.add(field.offset);
-  const sizeByKind = { bool: 1, u8: 1, s8: 1, u16: 2, s16: 2, u32: 4, s32: 4,
-    float: 4, u64: 8, s64: 8, double: 8, pointer: Process.pointerSize };
-  if (field.kind === 'utf8') {
-    const length = Math.min(field.maxBytes || maxStringBytes, maxStringBytes);
-    readable(address, 1);
-    return address.readUtf8String(length);
-  }
-  if (field.kind === 'bytes') {
-    const length = field.size;
-    readable(address, length);
-    const value = address.readByteArray(length);
-    return Array.from(new Uint8Array(value)).map(v => v.toString(16).padStart(2, '0')).join('');
-  }
-  const size = sizeByKind[field.kind];
-  if (!size) throw new Error('unsupported field kind ' + field.kind);
-  readable(address, size);
-  switch (field.kind) {
-    case 'bool': return address.readU8() !== 0;
-    case 'u8': return address.readU8(); case 's8': return address.readS8();
-    case 'u16': return address.readU16(); case 's16': return address.readS16();
-    case 'u32': return address.readU32(); case 's32': return address.readS32();
-    case 'float': return address.readFloat(); case 'double': return address.readDouble();
-    case 'u64': return address.readU64().toString(); case 's64': return address.readS64().toString();
-    case 'pointer': return address.readPointer().toString();
-  }
-}
-function validateInvariant(rule, address, fields, module) {
-  if (rule.kind === 'non_null') return { kind: rule.kind, passed: !address.isNull() };
-  if (rule.kind === 'aligned') return { kind: rule.kind, passed: address.and(rule.alignment - 1).isNull() };
-  if (rule.kind === 'field_range') {
-    const value = Number(fields[rule.field]);
-    return { kind: rule.kind, field: rule.field, passed: Number.isFinite(value) && value >= rule.minimum && value <= rule.maximum };
-  }
-  if (rule.kind === 'field_equals') return { kind: rule.kind, field: rule.field, passed: String(fields[rule.field]) === String(rule.value) };
-  if (rule.kind === 'vtable_in_module') {
-    const pointer = address.add(rule.offset || 0).readPointer();
-    const passed = pointer.compare(module.base) >= 0 && pointer.compare(module.base.add(module.size)) < 0;
-    return { kind: rule.kind, pointer: pointer.toString(), passed };
-  }
-  return { kind: rule.kind, passed: false, error: 'unsupported invariant' };
-}
-rpc.exports = {
-  readDataSource(plan, requestedLimit) {
-    const module = Process.getModuleByName(plan.moduleName);
-    const rva = Number(plan.root.rva);
-    if (!Number.isSafeInteger(rva) || rva < 0 || rva >= module.size) {
-      return { allPassed: false, error: 'root RVA is outside module', moduleBase: module.base.toString() };
-    }
-    try {
-      const rootAddress = module.base.add(rva);
-      let address = rootAddress;
-      if (plan.root.kind === 'global_pointer_rva') { readable(address, Process.pointerSize); address = address.readPointer(); }
-      for (const step of plan.pointerChain) {
-        address = address.add(step.offset);
-        if (step.dereference) { readable(address, Process.pointerSize); address = address.readPointer(); }
-      }
-      if (address.isNull()) throw new Error('resolved root is null');
-      const fields = {};
-      for (const field of plan.fields) fields[field.name] = readField(address, field, plan.maxStringBytes);
-      const validations = plan.invariants.map(rule => validateInvariant(rule, address, fields, module));
-      const result = { dataSourceId: plan.dataSourceId, buildKey: plan.buildKey, moduleName: module.name,
-        moduleBase: module.base.toString(), rootRva: plan.root.rva, rootAddress: rootAddress.toString(),
-        resolvedAddress: address.toString(), fields, validations, items: [] };
-      if (plan.container && plan.container.kind === 'vector') {
-        const begin = address.add(plan.container.beginOffset).readPointer();
-        const end = address.add(plan.container.endOffset).readPointer();
-        const byteLength = Number(BigInt(end.toString()) - BigInt(begin.toString()));
-        const elementSize = plan.container.elementSize;
-        const count = byteLength >= 0 && byteLength % elementSize === 0 ? byteLength / elementSize : -1;
-        const limit = Math.min(requestedLimit, plan.maxItems);
-        validations.push({ kind: 'vector_bounds', passed: count >= 0 && count <= plan.maxItems, count });
-        if (count >= 0 && count <= plan.maxItems) {
-          for (let index = 0; index < Math.min(count, limit); index++) {
-            const itemAddress = begin.add(index * elementSize);
-            const item = {};
-            for (const field of plan.container.fields || []) item[field.name] = readField(itemAddress, field, plan.maxStringBytes);
-            result.items.push({ index, address: itemAddress.toString(), fields: item });
-          }
-        }
-      }
-      result.allPassed = validations.length > 0 && validations.every(item => item.passed === true);
-      return result;
-    } catch (error) {
-      return { dataSourceId: plan.dataSourceId, buildKey: plan.buildKey, moduleName: module.name,
-        moduleBase: module.base.toString(), rootRva: plan.root.rva, allPassed: false, error: String(error) };
-    }
-  }
-};
-`;
-export class WowAnalysisService {
-    executor;
-    profileRoot;
-    packagedProfiles;
-    buildBundles;
-    moduleName;
-    options;
-    sessions = new Map();
-    luaTrace;
-    cppTrace;
-    closing = false;
-    constructor(options) {
-        if (!options || typeof options.executor?.execute !== "function")
-            throw new TypeError("executor is required");
-        this.executor = options.executor;
-        this.profileRoot = resolve(requiredString(options.profileRoot ?? options.artifactDir, "profileRoot"));
-        this.packagedProfiles = options.profileRoot !== undefined;
-        this.buildBundles = this.packagedProfiles ? new BuildBundleStore(this.profileRoot) : undefined;
-        this.moduleName = options.moduleName ?? WOW_ANALYSIS_MODULE;
-        this.options = options;
-    }
-    async invoke(operation, input = {}) {
-        switch (operation) {
-            case "wow_lua_trace_start": return this.wowLuaTraceStart(input);
-            case "wow_lua_trace_read": return this.wowLuaTraceRead(input);
-            case "wow_lua_trace_status": return this.wowLuaTraceStatus();
-            case "wow_lua_trace_stop": return this.wowLuaTraceStop(input);
-            case "wow_cpp_trace_start": return this.wowCppTraceStart(input);
-            case "wow_cpp_trace_read": return this.wowCppTraceRead(input);
-            case "wow_cpp_trace_status": return this.wowCppTraceStatus();
-            case "wow_cpp_trace_stop": return this.wowCppTraceStop(input);
-            case "wow_data_source_list": return this.wowDataSourceList(input);
-            case "wow_data_source_describe": return this.wowDataSourceDescribe(input);
-            case "wow_data_read": return this.wowDataRead(input);
-            case "wow_build_profile_validate": return this.wowBuildProfileValidate(input);
-            case "wow_analysis_coverage": return this.wowAnalysisCoverage(input);
-            case "wow_analysis_checkpoint": return this.wowAnalysisCheckpoint(input);
-        }
-    }
-    async wowLuaTraceStart(input) {
-        if (this.luaTrace)
-            throw new Error("Lua trace is already loaded; stop it before starting another trace");
-        const request = this.normalizeLuaStart(input);
-        const catalog = await this.loadLuaCatalog(input.buildKey);
-        const target = await this.acquireTarget(input.buildKey, input.pid);
-        let scriptId;
-        try {
-            const source = await this.luaSource();
-            const loaded = await this.executor.execute(brokerManagedCommand({
-                operation: "script_load",
-                sessionId: target.sessionId,
-                source
-            }, "wow.lua_trace.script_load"), target.context);
-            scriptId = requiredString(loaded.scriptId, "script_load.scriptId");
-            const configured = await this.callScript(scriptId, "configureLuaTrace", [catalog]);
-            const started = await this.callScript(scriptId, "wowLuaTraceStart", [{ ...request, pid: target.pid }]);
-            const value = isRecord(started.value) ? started.value : {};
-            this.assertRuntimeBase(value.moduleBase, target.moduleBase, "Lua trace");
-            this.luaTrace = { kind: "lua", scriptId, target, startedAt: new Date().toISOString() };
-            return {
-                ...value,
-                configured: configured.value,
-                sessionId: target.sessionId,
-                scriptId,
-                discoveredPid: target.pid,
-                discoveredModuleBase: target.moduleBase,
-                catalogRecords: arrayValue(catalog.targets).length,
-                abiProfiles: arrayValue(catalog.abiProfiles).length
-            };
-        }
-        catch (error) {
-            if (scriptId)
-                await this.unloadScript(scriptId).catch(() => undefined);
-            await this.releaseTarget(target).catch(() => undefined);
-            throw error;
-        }
-    }
-    async wowLuaTraceRead(input = {}) {
-        return this.readTrace("lua", input);
-    }
-    async wowLuaTraceStatus() {
-        return this.traceStatus("lua");
-    }
-    async wowLuaTraceStop(input = {}) {
-        return this.stopTrace("lua", input.reason ?? "requested");
-    }
-    async wowCppTraceStart(input) {
-        if (this.cppTrace)
-            throw new Error("C++ trace is already loaded; stop it before starting another trace");
-        const request = this.normalizeCppStart(input);
-        const catalog = await this.loadCppCatalog(input, request.maxHooks);
-        const target = await this.acquireTarget(input.buildKey, input.pid);
-        let scriptId;
-        try {
-            const loaded = await this.executor.execute(brokerManagedCommand({
-                operation: "script_load",
-                sessionId: target.sessionId,
-                source: this.options.cppTraceSource ?? CPP_TRACE_SOURCE
-            }, "wow.cpp_trace.script_load"), target.context);
-            scriptId = requiredString(loaded.scriptId, "script_load.scriptId");
-            const configured = await this.callScript(scriptId, "configureCppTrace", [catalog]);
-            const started = await this.callScript(scriptId, "wowCppTraceStart", [{ ...request, pid: target.pid }]);
-            const value = isRecord(started.value) ? started.value : {};
-            this.assertRuntimeBase(value.moduleBase, target.moduleBase, "C++ trace");
-            this.cppTrace = { kind: "cpp", scriptId, target, startedAt: new Date().toISOString() };
-            return {
-                ...value,
-                configured: configured.value,
-                sessionId: target.sessionId,
-                scriptId,
-                discoveredPid: target.pid,
-                discoveredModuleBase: target.moduleBase
-            };
-        }
-        catch (error) {
-            if (scriptId)
-                await this.unloadScript(scriptId).catch(() => undefined);
-            await this.releaseTarget(target).catch(() => undefined);
-            throw error;
-        }
-    }
-    async wowCppTraceRead(input = {}) {
-        return this.readTrace("cpp", input);
-    }
-    async wowCppTraceStatus() {
-        return this.traceStatus("cpp");
-    }
-    async wowCppTraceStop(input = {}) {
-        return this.stopTrace("cpp", input.reason ?? "requested");
-    }
-    async wowDataSourceList(input) {
-        const buildKey = requiredString(input.buildKey, "buildKey");
-        const records = await this.loadDataSources(buildKey);
-        const offset = boundedInteger(input.offset, 0, 0, Number.MAX_SAFE_INTEGER, "offset");
-        const limit = boundedInteger(input.limit, 100, 1, 1000, "limit");
-        const filtered = records.filter(record => {
-            const summary = summarizeRecord(record);
-            return (input.status === undefined || summary.status === input.status)
-                && (input.readerStatus === undefined || summary.readerStatus === input.readerStatus)
-                && (input.system === undefined || record.system === input.system);
-        });
-        return {
-            buildKey,
-            total: filtered.length,
-            offset,
-            limit,
-            dataSources: filtered.slice(offset, offset + limit).map(summarizeRecord)
-        };
-    }
-    async wowDataSourceDescribe(input) {
-        const buildKey = requiredString(input.buildKey, "buildKey");
-        const dataSourceId = requiredString(input.dataSourceId, "dataSourceId");
-        const source = await this.requireDataSource(buildKey, dataSourceId);
-        const profile = await this.readBuildProfile(buildKey);
-        const profileEntry = this.profileDataSource(profile, dataSourceId);
-        return {
-            buildKey,
-            dataSourceId,
-            summary: summarizeRecord(source),
-            source,
-            buildProfile: profileEntry ?? null,
-            formalReaderEligible: this.isReaderReady(source, profileEntry)
-        };
-    }
-    async wowDataRead(input) {
-        const buildKey = requiredString(input.buildKey, "buildKey");
-        const dataSourceId = requiredString(input.dataSourceId, "dataSourceId");
-        const source = await this.requireDataSource(buildKey, dataSourceId);
-        const profile = await this.readBuildProfile(buildKey);
-        const profileEntry = this.profileDataSource(profile, dataSourceId);
-        if (!this.isReaderReady(source, profileEntry)) {
-            throw new Error(`data source ${dataSourceId} is not reader_ready`);
-        }
-        const plan = this.normalizeReaderPlan(buildKey, dataSourceId, source, profileEntry);
-        const target = await this.acquireTarget(buildKey, input.pid);
-        let scriptId;
-        try {
-            const loaded = await this.executor.execute(brokerManagedCommand({
-                operation: "script_load",
-                sessionId: target.sessionId,
-                source: this.options.dataReaderSource ?? DATA_READER_SOURCE
-            }, "wow.data_reader.script_load"), target.context);
-            scriptId = requiredString(loaded.scriptId, "script_load.scriptId");
-            const result = await this.callScript(scriptId, "readDataSource", [plan, boundedInteger(input.limit, plan.maxItems, 1, plan.maxItems, "limit")]);
-            const value = isRecord(result.value) ? result.value : { allPassed: false, error: "reader returned a non-object result" };
-            this.assertRuntimeBase(value.moduleBase, target.moduleBase, "data reader");
-            return {
-                ...value,
-                dataSourceId,
-                buildKey,
-                runtime: {
-                    pid: target.pid,
-                    module: target.moduleName,
-                    moduleBase: target.moduleBase,
-                    rootRva: plan.root.rva,
-                    rootRuntimeAddress: hexAdd(target.moduleBase, plan.root.rva)
-                },
-                readerDefinition: plan,
-                crossVerificationEvidence: source.liveEvidence ?? source.verificationEvidence ?? profileEntry?.liveEvidence ?? []
-            };
-        }
-        finally {
-            if (scriptId)
-                await this.unloadScript(scriptId).catch(() => undefined);
-            await this.releaseTarget(target).catch(() => undefined);
-        }
-    }
-    async wowBuildProfileValidate(input) {
-        const buildKey = requiredString(input.buildKey, "buildKey");
-        const profile = await this.readBuildProfile(buildKey);
-        const signatureSource = this.packagedProfiles
-            ? await this.buildBundles.readJson(buildKey, "signatures.json")
-            : profile;
-        const target = await this.acquireTarget(buildKey, input.pid);
-        const checks = [];
-        try {
-            checks.push({
-                name: "build_key",
-                expected: buildKey,
-                actual: profile.buildKey,
-                passed: profile.buildKey === buildKey
-            });
-            const profileModule = normalizeModuleName(profile.module ?? profile.moduleName, this.moduleName);
-            checks.push({ name: "module_name", expected: profileModule, actual: target.moduleName, passed: profileModule.toLowerCase() === target.moduleName.toLowerCase() });
-            checks.push({ name: "runtime_base_dynamic", actual: target.moduleBase, passed: /^0x[0-9a-f]+$/i.test(target.moduleBase) });
-            checks.push({ name: "image_base", expected: WOW_IDA_IMAGE_BASE, actual: profile.imageBase, passed: normalizeHex(profile.imageBase ?? WOW_IDA_IMAGE_BASE, "imageBase") === WOW_IDA_IMAGE_BASE });
-            const signatures = this.signatureRecords(signatureSource).slice(0, boundedInteger(input.maxChecks, 128, 1, MAX_SIGNATURE_CHECKS, "maxChecks"));
-            if (signatures.length === 0) {
-                checks.push({ name: "signature_evidence_present", passed: false, error: "build profile contains no verifiable entry signatures" });
-            }
-            for (let index = 0; index < signatures.length; index++) {
-                checks.push(await this.verifySignature(target, signatures[index], index));
-            }
-            const profileSources = recordsFrom(profile, ["dataSources", "dataRoots"]);
-            for (const record of profileSources.filter(item => this.isReaderReady(item)).slice(0, MAX_SIGNATURE_CHECKS)) {
-                const id = stringValue(record.dataSourceId ?? record.id) ?? "unknown";
-                try {
-                    this.normalizeReaderPlan(buildKey, id, record, record);
-                    checks.push({ name: `reader_definition:${id}`, passed: true });
-                }
-                catch (error) {
-                    checks.push({ name: `reader_definition:${id}`, passed: false, error: errorText(error) });
-                }
-            }
-            const allPassed = checks.length > 0 && checks.every(check => check.passed === true);
-            return {
-                buildKey,
-                pid: target.pid,
-                module: target.moduleName,
-                moduleBase: target.moduleBase,
-                moduleSize: target.moduleSize,
-                imageBase: WOW_IDA_IMAGE_BASE,
-                checks,
-                checkedSignatures: signatures.length,
-                allPassed,
-                status: allPassed ? "passed" : "failed"
-            };
-        }
-        finally {
-            await this.releaseTarget(target).catch(() => undefined);
-        }
-    }
-    async wowAnalysisCoverage(input) {
-        const buildKey = requiredString(input.buildKey, "buildKey");
-        const suffix = buildSuffix(buildKey);
-        const artifacts = [];
-        for (const spec of REQUIRED_ARTIFACTS) {
-            const path = join(this.profileRoot, spec.file(suffix));
-            try {
-                const data = await readFile(path);
-                let parsed;
-                let parsePassed = true;
-                if (spec.json) {
-                    try {
-                        parsed = JSON.parse(data.toString("utf8"));
-                    }
-                    catch {
-                        parsePassed = false;
-                    }
-                }
-                artifacts.push({
-                    key: spec.key,
-                    role: spec.role,
-                    file: path,
-                    exists: true,
-                    size: data.byteLength,
-                    sha256: sha256(data),
-                    parsePassed,
-                    ...(isRecord(parsed) && parsed.buildKey !== undefined ? { artifactBuildKey: parsed.buildKey, buildMatches: parsed.buildKey === buildKey } : {}),
-                    ...(isRecord(parsed) && isRecord(parsed.counts) ? { counts: parsed.counts } : {}),
-                    ...(isRecord(parsed) && parsed.summary !== undefined ? { summary: parsed.summary } : {})
-                });
-            }
-            catch (error) {
-                const code = isRecord(error) ? error.code : undefined;
-                artifacts.push({ key: spec.key, role: spec.role, file: path, exists: false, error: code === "ENOENT" ? null : errorText(error) });
-            }
-        }
-        const wrapper = await this.readArtifactOptional(buildKey, "lua-wrapper-coverage");
-        const callgraph = await this.readArtifactOptional(buildKey, "lua-wrapper-callgraph");
-        const clusters = await this.readArtifactOptional(buildKey, "cpp-implementation-clusters");
-        const dataSources = await this.readArtifactOptional(buildKey, "cpp-data-sources");
-        const nonLua = await this.readArtifactOptional(buildKey, "non-lua-system-coverage");
-        const wrapperRecords = recordsFrom(wrapper, ["records", "wrappers"]);
-        const callgraphRecords = recordsFrom(callgraph, ["records", "wrappers"]);
-        const clusterRecords = recordsFrom(clusters, ["clusters"]);
-        const dataSourceRecords = recordsFrom(dataSources, ["dataSources"]);
-        const nonLuaRecords = recordsFrom(nonLua, ["systems", "records"]);
-        return {
-            buildKey,
-            profileRoot: this.profileRoot,
-            generatedAt: new Date().toISOString(),
-            requiredArtifacts: artifacts.length,
-            presentArtifacts: artifacts.filter(item => item.exists === true).length,
-            missingArtifacts: artifacts.filter(item => item.exists !== true).map(item => item.file),
-            artifacts,
-            matrix: {
-                luaWrappers: this.statusCounts(wrapperRecords),
-                callgraph: this.statusCounts(callgraphRecords),
-                clusters: this.statusCounts(clusterRecords),
-                dataSources: this.statusCounts(dataSourceRecords, "readerStatus"),
-                nonLuaSystems: this.statusCounts(nonLuaRecords)
-            },
-            completion: {
-                wrapperRecords: wrapperRecords.length,
-                wrapperDenominator: 5130,
-                allWrappersPresent: wrapperRecords.length === 5130,
-                callgraphRecords: callgraphRecords.length,
-                clusters: clusterRecords.length,
-                dataSources: dataSourceRecords.length,
-                nonLuaSystems: nonLuaRecords.length
-            }
-        };
-    }
-    async wowAnalysisCheckpoint(input) {
-        const coverage = await this.wowAnalysisCoverage(input);
-        const luaTrace = await this.wowLuaTraceStatus().catch(error => ({ active: false, error: errorText(error) }));
-        const cppTrace = await this.wowCppTraceStatus().catch(error => ({ active: false, error: errorText(error) }));
-        const timestamp = new Date().toISOString();
-        return {
-            buildKey: input.buildKey,
-            label: input.label ?? "manual",
-            timestamp,
-            coverage,
-            traces: { lua: luaTrace, cpp: cppTrace },
-            suggestedProcessEvent: {
-                timestamp,
-                buildKey: input.buildKey,
-                phase: "verify",
-                action: "checkpoint",
-                tool: "wow-analysis-service",
-                target: { name: this.moduleName, imageBase: WOW_IDA_IMAGE_BASE },
-                result: {
-                    label: input.label ?? "manual",
-                    presentArtifacts: coverage.presentArtifacts,
-                    requiredArtifacts: coverage.requiredArtifacts,
-                    completion: coverage.completion
-                },
-                status: coverage.missingArtifacts instanceof Array && coverage.missingArtifacts.length === 0 ? "passed" : "partial",
-                artifacts: (coverage.artifacts instanceof Array ? coverage.artifacts : []).filter(isRecord).filter(item => item.exists === true).map(item => item.file),
-                error: null,
-                nextAction: "continue unresolved and partial coverage entries"
-            }
-        };
-    }
-    async close() {
-        if (this.closing)
-            return;
-        this.closing = true;
-        try {
-            await this.stopTrace("lua", "service_close").catch(() => undefined);
-            await this.stopTrace("cpp", "service_close").catch(() => undefined);
-            for (const lease of [...this.sessions.values()]) {
-                if (lease.owned) {
-                    await this.executor.execute({ operation: "detach", sessionId: lease.sessionId }, lease.context).catch(() => undefined);
-                }
-                this.sessions.delete(lease.sessionId);
-            }
-            if (this.options.closeExecutorOnClose)
-                await this.executor.close();
-        }
-        finally {
-            this.closing = false;
-        }
-    }
-    normalizeLuaStart(input) {
-        requiredString(input.buildKey, "buildKey");
-        requireSelection(input);
-        const APIs = normalizeApiList(input);
-        const rva = normalizeRvaSelection(input.rva);
-        return {
-            buildKey: input.buildKey,
-            ...(APIs.length ? { APIs } : {}),
-            ...(input.namespace === undefined ? {} : { namespace: requiredString(input.namespace, "namespace") }),
-            ...(input.glob === undefined ? {} : { glob: requiredString(input.glob, "glob") }),
-            ...(rva.length ? { rva } : {}),
-            all: input.all === true,
-            captureArgs: input.captureArgs ?? true,
-            captureReturns: input.captureReturns ?? true,
-            captureNativeArguments: input.captureNativeArguments ?? false,
-            tableDepth: boundedInteger(input.tableDepth, 2, 0, 8, "tableDepth"),
-            maxItems: boundedInteger(input.maxItems, 64, 1, 1000, "maxItems"),
-            maxStringBytes: boundedInteger(input.maxStringBytes, 4096, 1, MAX_STRING_BYTES, "maxStringBytes"),
-            maxStackValues: boundedInteger(input.maxStackValues, 128, 1, 1000, "maxStackValues"),
-            maxInvocationDepth: boundedInteger(input.maxInvocationDepth, 64, 1, 1024, "maxInvocationDepth"),
-            maxDecodeMs: boundedInteger(input.maxDecodeMs, 25, 1, 1000, "maxDecodeMs"),
-            maxEvents: boundedInteger(input.maxEvents, 10_000, 1, MAX_EVENTS, "maxEvents"),
-            maxHooks: boundedInteger(input.maxHooks, DEFAULT_MAX_HOOKS, 1, MAX_LUA_HOOKS, "maxHooks"),
-            sampling: boundedSampling(input.sampling),
-            durationMs: boundedInteger(input.durationMs, 0, 0, 24 * 60 * 60 * 1000, "durationMs"),
-            allowTableIteration: input.allowTableIteration ?? false,
-            staleInvocationMs: boundedInteger(input.staleInvocationMs, 600_000, 1000, 24 * 60 * 60 * 1000, "staleInvocationMs")
-        };
-    }
-    normalizeCppStart(input) {
-        requiredString(input.buildKey, "buildKey");
-        requireSelection(input);
-        return {
-            buildKey: input.buildKey,
-            captureArguments: input.captureArguments ?? true,
-            captureReturn: input.captureReturn ?? true,
-            argumentCount: boundedInteger(input.argumentCount, 4, 0, 8, "argumentCount"),
-            maxEvents: boundedInteger(input.maxEvents, 10_000, 1, MAX_EVENTS, "maxEvents"),
-            maxHooks: boundedInteger(input.maxHooks, 32, 1, MAX_CPP_HOOKS, "maxHooks"),
-            sampling: boundedSampling(input.sampling),
-            durationMs: boundedInteger(input.durationMs, 0, 0, 24 * 60 * 60 * 1000, "durationMs")
-        };
-    }
-    async acquireTarget(buildKeyValue, requestedPid) {
-        const buildKey = requiredString(buildKeyValue, "buildKey");
-        if (requestedPid !== undefined)
-            boundedInteger(requestedPid, requestedPid, 1, Number.MAX_SAFE_INTEGER, "pid");
-        const processesResult = await this.executor.execute({ operation: "processes" });
-        const wowProcesses = resultArray(processesResult, "processes").filter(process => {
-            const name = stringValue(process.name) ?? "";
-            const pid = integerValue(process.pid);
-            return name.toLowerCase() === this.moduleName.toLowerCase()
-                && pid !== undefined
-                && (requestedPid === undefined || pid === requestedPid);
-        });
-        if (wowProcesses.length === 0 && requestedPid === undefined) {
-            throw new Error(`${this.moduleName} is not running or is hidden from Frida process enumeration`);
-        }
-        if (wowProcesses.length > 1 && requestedPid === undefined) {
-            throw new Error(`multiple ${this.moduleName} processes are running; specify pid`);
-        }
-        const pid = requestedPid ?? integerValue(wowProcesses[0].pid);
-        const context = { pid, buildKey, flavor: flavorForBuild(buildKey) };
-        const attached = await this.executor.execute({ operation: "attach", pid, buildKey }, context);
-        const sessionId = requiredString(attached.sessionId, "attach.sessionId");
-        const existingLease = this.sessions.get(sessionId);
-        const newlyOwned = existingLease === undefined && attached.reused !== true;
-        try {
-            const modulesResult = await this.executor.execute({ operation: "modules", sessionId }, context);
-            const module = resultArray(modulesResult, "modules").find(item => stringValue(item.name)?.toLowerCase() === this.moduleName.toLowerCase());
-            if (!module)
-                throw new Error(`${this.moduleName} was not found in PID ${pid}`);
-            const moduleBase = normalizeHex(module.base, "module.base");
-            const moduleSize = boundedInteger(module.size, 0, 1, Number.MAX_SAFE_INTEGER, "module.size");
-            const target = {
-                sessionId,
-                pid,
-                buildKey,
-                context,
-                moduleName: stringValue(module.name) ?? this.moduleName,
-                moduleBase,
-                moduleSize,
-                owned: existingLease?.owned ?? newlyOwned
-            };
-            if (existingLease)
-                existingLease.references++;
-            else
-                this.sessions.set(sessionId, { ...target, references: 1 });
-            return target;
-        }
-        catch (error) {
-            if (newlyOwned)
-                await this.executor.execute({ operation: "detach", sessionId }, context).catch(() => undefined);
-            throw error;
-        }
-    }
-    async releaseTarget(target) {
-        const lease = this.sessions.get(target.sessionId);
-        if (!lease)
-            return;
-        lease.references--;
-        if (lease.references > 0)
-            return;
-        this.sessions.delete(target.sessionId);
-        if (lease.owned)
-            await this.executor.execute({ operation: "detach", sessionId: lease.sessionId }, lease.context);
-    }
-    async luaSource() {
-        if (typeof this.options.luaTraceSource === "string")
-            return this.options.luaTraceSource;
-        if (typeof this.options.luaTraceSource === "function")
-            return this.options.luaTraceSource();
-        const path = this.options.luaTraceScriptFile ?? resolve("dist", "agent.js");
-        return readFile(path, "utf8");
-    }
-    async callScript(scriptId, exportName, args = []) {
-        return this.executor.execute(brokerManagedCommand({ operation: "script_call", scriptId, exportName, args }, `wow.analysis.${exportName}`));
-    }
-    async unloadScript(scriptId) {
-        await this.executor.execute(brokerManagedCommand({ operation: "script_unload", scriptId }, "wow.analysis.script_unload"));
-    }
-    activeTrace(kind) {
-        return kind === "lua" ? this.luaTrace : this.cppTrace;
-    }
-    setActiveTrace(kind, value) {
-        if (kind === "lua")
-            this.luaTrace = value;
-        else
-            this.cppTrace = value;
-    }
-    rpcName(kind, operation) {
-        return `wow${kind === "lua" ? "Lua" : "Cpp"}Trace${operation}`;
-    }
-    async readTrace(kind, input) {
-        const trace = this.activeTrace(kind);
-        if (!trace)
-            return { active: false, events: [], oldestSeq: null, newestSeq: null, nextAfterSeq: input.afterSeq ?? 0, droppedEvents: 0 };
-        const afterSeq = boundedInteger(input.afterSeq, 0, 0, Number.MAX_SAFE_INTEGER, "afterSeq");
-        const limit = boundedInteger(input.limit, 1000, 1, 10_000, "limit");
-        const result = await this.callScript(trace.scriptId, this.rpcName(kind, "Read"), [afterSeq, limit]);
-        return { active: true, sessionId: trace.target.sessionId, scriptId: trace.scriptId, ...(isRecord(result.value) ? result.value : { value: result.value }) };
-    }
-    async traceStatus(kind) {
-        const trace = this.activeTrace(kind);
-        if (!trace)
-            return { active: false, loaded: false, kind };
-        const result = await this.callScript(trace.scriptId, this.rpcName(kind, "Status"));
-        return {
-            loaded: true,
-            kind,
-            sessionId: trace.target.sessionId,
-            scriptId: trace.scriptId,
-            discoveredPid: trace.target.pid,
-            discoveredModuleBase: trace.target.moduleBase,
-            ...(isRecord(result.value) ? result.value : { value: result.value })
-        };
-    }
-    async stopTrace(kind, reason) {
-        const trace = this.activeTrace(kind);
-        if (!trace)
-            return { active: false, loaded: false, kind, cleanup: { scriptUnloaded: true, sessionReleased: true } };
-        this.setActiveTrace(kind, undefined);
-        let stopped;
-        const errors = [];
-        try {
-            stopped = (await this.callScript(trace.scriptId, this.rpcName(kind, "Stop"), [reason])).value;
-        }
-        catch (error) {
-            errors.push(`stop RPC: ${errorText(error)}`);
-        }
-        try {
-            await this.callScript(trace.scriptId, "dispose");
-        }
-        catch (error) {
-            errors.push(`dispose RPC: ${errorText(error)}`);
-        }
-        try {
-            await this.unloadScript(trace.scriptId);
-        }
-        catch (error) {
-            errors.push(`script unload: ${errorText(error)}`);
-        }
-        try {
-            await this.releaseTarget(trace.target);
-        }
-        catch (error) {
-            errors.push(`session release: ${errorText(error)}`);
-        }
-        return {
-            ...(isRecord(stopped) ? stopped : { active: false }),
-            loaded: false,
-            kind,
-            reason,
-            cleanup: { scriptUnloaded: !errors.some(item => item.startsWith("script unload")), sessionReleased: !errors.some(item => item.startsWith("session release")), errors }
-        };
-    }
-    assertRuntimeBase(actual, expected, label) {
-        if (actual === undefined || actual === null)
-            return;
-        if (normalizeHex(actual, `${label}.moduleBase`) !== normalizeHex(expected, "discovered module base")) {
-            throw new Error(`${label} reported module base ${String(actual)}, expected dynamically discovered ${expected}`);
-        }
-    }
-    artifactPath(buildKey, stem) {
-        if (!this.packagedProfiles)
-            return join(this.profileRoot, `${stem}-${buildSuffix(buildKey)}.json`);
-        const names = {
-            "build-profile": "build-profile.json",
-            "cpp-data-sources": "data-sources.json",
-            "wow-lua-api-all-rva": "lua-targets.jsonl"
-        };
-        return names[stem];
-    }
-    async readArtifact(buildKey, stem) {
-        const path = this.artifactPath(buildKey, stem);
-        if (!path)
-            throw new Error(`${stem} is not included in the packaged build bundle for ${buildKey}`);
-        let value;
-        try {
-            const text = this.packagedProfiles
-                ? await this.buildBundles.readText(buildKey, path)
-                : await readFile(path, "utf8");
-            value = path.endsWith(".jsonl")
-                ? { buildKey, records: text.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line)) }
-                : JSON.parse(text);
-        }
-        catch (error) {
-            throw new Error(`failed to read ${basename(path)}: ${errorText(error)}`);
-        }
-        if (!isRecord(value))
-            throw new Error(`${basename(path)} must contain a JSON object`);
-        if (value.buildKey !== undefined && value.buildKey !== buildKey) {
-            throw new Error(`${basename(path)} belongs to ${String(value.buildKey)}, not ${buildKey}`);
-        }
-        return value;
-    }
-    async readArtifactOptional(buildKey, stem) {
-        if (this.packagedProfiles && !this.artifactPath(buildKey, stem))
-            return undefined;
-        try {
-            return await this.readArtifact(buildKey, stem);
-        }
-        catch (error) {
-            if (/failed to read .*ENOENT|no such file or directory/i.test(errorText(error)))
-                return undefined;
-            throw error;
-        }
-    }
-    async readBuildProfile(buildKey) {
-        return this.readArtifact(buildKey, "build-profile");
-    }
-    async loadDataSources(buildKey) {
-        const artifact = await this.readArtifact(buildKey, "cpp-data-sources");
-        return recordsFrom(artifact, ["dataSources", "records"]);
-    }
-    async requireDataSource(buildKey, dataSourceId) {
-        const records = await this.loadDataSources(buildKey);
-        const source = records.find(record => stringValue(record.dataSourceId ?? record.id) === dataSourceId);
-        if (!source)
-            throw new Error(`data source ${dataSourceId} was not found for ${buildKey}`);
-        if (source.buildKey !== undefined && source.buildKey !== buildKey)
-            throw new Error(`data source ${dataSourceId} has a build mismatch`);
-        return source;
-    }
-    profileDataSource(profile, dataSourceId) {
-        const records = recordsFrom(profile, ["dataSources", "dataRoots", "readers"]);
-        return records.find(record => stringValue(record.dataSourceId ?? record.id) === dataSourceId);
-    }
-    isReaderReady(source, profileEntry) {
-        const statuses = [
-            statusValue(source, "readerStatus", "reader_status"),
-            isRecord(source.reader) ? statusValue(source.reader, "status", "readerStatus") : undefined,
-            profileEntry ? statusValue(profileEntry, "readerStatus", "reader_status") : undefined,
-            profileEntry && isRecord(profileEntry.reader) ? statusValue(profileEntry.reader, "status", "readerStatus") : undefined
-        ];
-        return statuses.some(value => value === "reader_ready");
-    }
-    normalizeReaderPlan(buildKey, dataSourceId, source, profileEntry) {
-        const candidates = [
-            profileEntry?.readerDefinition,
-            profileEntry?.reader,
-            source.readerDefinition,
-            source.reader,
-            profileEntry,
-            source
-        ];
-        const reader = candidates.find(isRecord);
-        if (!reader)
-            throw new Error(`data source ${dataSourceId} has no reader definition`);
-        const rootCandidate = isRecord(reader.root) ? reader.root : {};
-        const rawKind = stringValue(rootCandidate.kind ?? reader.rootKind);
-        const kindAliases = {
-            module_rva: "module_rva",
-            moduleRva: "module_rva",
-            module_address: "module_rva",
-            global_pointer_rva: "global_pointer_rva",
-            globalPointerRva: "global_pointer_rva",
-            global_pointer: "global_pointer_rva"
-        };
-        const kind = rawKind ? kindAliases[rawKind] : undefined;
-        if (!kind)
-            throw new Error(`data source ${dataSourceId} reader root kind is missing or unsupported`);
-        const rawRva = rootCandidate.rva ?? reader.rootRva ?? (kind === "global_pointer_rva" ? source.globalPointerRva ?? profileEntry?.globalPointerRva : undefined);
-        const rva = normalizeHex(rawRva, `${dataSourceId}.reader.root.rva`);
-        const rawChain = arrayValue(reader.pointerChain ?? source.pointerChain ?? profileEntry?.pointerChain);
-        if (rawChain.length > 16)
-            throw new Error(`${dataSourceId}.pointerChain exceeds 16 steps`);
-        const pointerChain = rawChain.map((step, index) => {
-            if (typeof step === "number")
-                return { offset: boundedInteger(step, 0, 0, 0x1000000, `pointerChain[${index}]`), dereference: true };
-            if (!isRecord(step))
-                throw new Error(`pointerChain[${index}] must be an offset or object`);
-            return {
-                offset: boundedInteger(step.offset, 0, 0, 0x1000000, `pointerChain[${index}].offset`),
-                dereference: booleanValue(step.dereference) ?? true
-            };
-        });
-        const rawFields = arrayValue(reader.fields ?? source.fields ?? profileEntry?.fields);
-        if (rawFields.length > 256)
-            throw new Error(`${dataSourceId}.fields exceeds 256 entries`);
-        const supportedKinds = new Set(["bool", "u8", "s8", "u16", "s16", "u32", "s32", "u64", "s64", "float", "double", "pointer", "utf8", "bytes"]);
-        const fields = rawFields.map((field, index) => {
-            if (!isRecord(field))
-                throw new Error(`fields[${index}] must be an object`);
-            const name = requiredString(field.name, `fields[${index}].name`);
-            const kindValue = requiredString(field.kind ?? field.type, `fields[${index}].kind`);
-            if (!supportedKinds.has(kindValue))
-                throw new Error(`fields[${index}].kind ${kindValue} is unsupported`);
-            const normalized = {
-                name,
-                offset: boundedInteger(field.offset, 0, 0, 0x1000000, `fields[${index}].offset`),
-                kind: kindValue
-            };
-            if (kindValue === "utf8")
-                normalized.maxBytes = boundedInteger(field.maxBytes, 4096, 1, MAX_STRING_BYTES, `fields[${index}].maxBytes`);
-            if (kindValue === "bytes")
-                normalized.size = boundedInteger(field.size, 1, 1, 4096, `fields[${index}].size`);
-            return normalized;
-        });
-        const rawInvariants = arrayValue(reader.validationRules ?? reader.invariants ?? source.validationRules ?? profileEntry?.validationRules);
-        if (rawInvariants.length === 0)
-            throw new Error(`data source ${dataSourceId} reader has no machine-checkable validation rules`);
-        if (rawInvariants.length > 128)
-            throw new Error(`${dataSourceId}.validationRules exceeds 128 entries`);
-        const allowedInvariants = new Set(["non_null", "aligned", "field_range", "field_equals", "vtable_in_module"]);
-        const invariants = rawInvariants.map((rule, index) => {
-            if (!isRecord(rule))
-                throw new Error(`validationRules[${index}] must be an object`);
-            const kindValue = requiredString(rule.kind ?? rule.type, `validationRules[${index}].kind`);
-            if (!allowedInvariants.has(kindValue))
-                throw new Error(`validationRules[${index}].kind ${kindValue} is unsupported`);
-            if (kindValue === "aligned")
-                boundedInteger(rule.alignment, 8, 1, 4096, `validationRules[${index}].alignment`);
-            if (kindValue === "field_range") {
-                requiredString(rule.field, `validationRules[${index}].field`);
-                if (typeof rule.minimum !== "number" || typeof rule.maximum !== "number")
-                    throw new Error(`validationRules[${index}] requires numeric minimum/maximum`);
-            }
-            return { ...rule, kind: kindValue };
-        });
-        let container;
-        if (reader.container !== undefined) {
-            if (!isRecord(reader.container) || reader.container.kind !== "vector")
-                throw new Error(`${dataSourceId}.container currently supports only vector`);
-            const containerFields = arrayValue(reader.container.fields).map((field, index) => {
-                if (!isRecord(field))
-                    throw new Error(`container.fields[${index}] must be an object`);
-                const kindValue = requiredString(field.kind ?? field.type, `container.fields[${index}].kind`);
-                if (!supportedKinds.has(kindValue))
-                    throw new Error(`container.fields[${index}].kind ${kindValue} is unsupported`);
-                return {
-                    name: requiredString(field.name, `container.fields[${index}].name`),
-                    offset: boundedInteger(field.offset, 0, 0, 0x1000000, `container.fields[${index}].offset`),
-                    kind: kindValue,
-                    ...(kindValue === "utf8" ? { maxBytes: boundedInteger(field.maxBytes, 4096, 1, MAX_STRING_BYTES, `container.fields[${index}].maxBytes`) } : {}),
-                    ...(kindValue === "bytes" ? { size: boundedInteger(field.size, 1, 1, 4096, `container.fields[${index}].size`) } : {})
-                };
-            });
-            container = {
-                kind: "vector",
-                beginOffset: boundedInteger(reader.container.beginOffset, 0, 0, 0x1000000, "container.beginOffset"),
-                endOffset: boundedInteger(reader.container.endOffset, 8, 0, 0x1000000, "container.endOffset"),
-                elementSize: boundedInteger(reader.container.elementSize, 1, 1, 0x100000, "container.elementSize"),
-                fields: containerFields
-            };
-        }
-        return {
-            dataSourceId,
-            buildKey,
-            moduleName: normalizeModuleName(reader.module ?? source.module ?? profileEntry?.module, this.moduleName),
-            root: { kind, rva },
-            pointerChain,
-            fields,
-            invariants,
-            ...(container ? { container } : {}),
-            maxItems: boundedInteger(reader.maxItems, 1024, 1, MAX_READ_ITEMS, "reader.maxItems"),
-            maxStringBytes: boundedInteger(reader.maxStringBytes, 4096, 1, MAX_STRING_BYTES, "reader.maxStringBytes")
-        };
-    }
-    async loadLuaCatalog(buildKey) {
-        const manifest = await this.readArtifact(buildKey, "wow-lua-api-all-rva");
-        const abi = await this.readArtifactOptional(buildKey, "lua-abi")
-            ?? await this.readArtifactOptional(buildKey, "lua-abi-static-evidence")
-            ?? {};
-        const coverage = await this.readArtifactOptional(buildKey, "lua-wrapper-coverage") ?? {};
-        const records = recordsFrom(manifest, ["records"]);
-        if (records.length === 0)
-            throw new Error("Lua registration manifest has no records");
-        const profiles = this.luaAbiProfiles(abi, buildKey);
-        const evidenceRecords = [
-            ...recordsFrom(abi, ["callbacks", "targets", "records"]),
-            ...recordsFrom(coverage, ["records", "wrappers"])
-        ];
-        const evidenceByKey = new Map();
-        for (const record of evidenceRecords)
-            evidenceByKey.set(this.luaRecordKey(record), record);
-        const defaultProfileId = profiles.length === 1 ? stringValue(profiles[0].id) : undefined;
-        const targets = records.map((record, index) => {
-            const namespace = stringValue(record.namespace) ?? "global";
-            const name = requiredString(record.name, `records[${index}].name`);
-            const rva = normalizeHex(record.rva ?? record.wrapperRva, `records[${index}].rva`);
-            const evidence = evidenceByKey.get(this.luaRecordKey({ namespace, name, rva })) ?? {};
-            const rawAbi = isRecord(record.abi) ? record.abi : isRecord(evidence.abi) ? evidence.abi : {};
-            const callback = isRecord(evidence.standardLuaCallback) ? evidence.standardLuaCallback : {};
-            const argument = isRecord(evidence.luaStateArgument) ? evidence.luaStateArgument : {};
-            const evidenceStatus = stringValue(rawAbi.status ?? evidence.abiStatus ?? callback.status);
-            const profileId = stringValue(rawAbi.profileId ?? evidence.profileId) ?? defaultProfileId ?? "unresolved";
-            const hasProfile = profiles.some(profile => profile.id === profileId);
-            const luaStateArgIndex = integerValue(rawAbi.luaStateArgIndex)
-                ?? integerValue(evidence.luaStateArgIndex)
-                ?? (stringValue(argument.register)?.toUpperCase() === "RCX" ? 0 : undefined);
-            const confirmed = hasProfile && luaStateArgIndex !== undefined && ["confirmed", "dynamically_verified", "abi_resolved"].includes(evidenceStatus ?? "");
-            return {
-                id: stringValue(record.id) ?? `${buildKey}:${namespace}.${name}:${rva}`,
-                buildKey,
-                namespace,
-                name,
-                rva,
-                registrationPrimitive: stringValue(record.registrationPrimitive) ?? "unresolved",
-                sourceKind: stringValue(record.sourceKind) ?? "unresolved",
-                abi: {
-                    status: confirmed ? (evidenceStatus === "dynamically_verified" ? "dynamically_verified" : "confirmed") : "unresolved",
-                    profileId,
-                    luaStateArgIndex: luaStateArgIndex ?? null,
-                    returnConvention: stringValue(rawAbi.returnConvention)
-                        ?? (callback.prototype !== undefined ? "lua_return_count_int32" : "opaque"),
-                    evidence: arrayValue(rawAbi.evidence).filter(item => typeof item === "string")
-                }
-            };
-        });
-        return { buildKey, moduleName: normalizeModuleName(manifest.module, this.moduleName), targets, abiProfiles: profiles };
-    }
-    luaRecordKey(record) {
-        const namespace = stringValue(record.namespace) ?? "global";
-        const name = stringValue(record.name) ?? "";
-        let rva = "";
-        try {
-            if (record.rva !== undefined || record.wrapperRva !== undefined)
-                rva = normalizeHex(record.rva ?? record.wrapperRva, "rva");
-        }
-        catch { /* key can fall back to API */ }
-        return `${namespace}\u0000${name}\u0000${rva}`;
-    }
-    luaAbiProfiles(artifact, buildKey) {
-        const candidates = recordsFrom(artifact, ["abiProfiles", "profiles"]);
-        if (candidates.length === 0) {
-            const singleton = [artifact.abiProfile, artifact.profile, artifact.luaAbiProfile].find(isRecord);
-            if (singleton)
-                candidates.push(singleton);
-        }
-        const profiles = [];
-        candidates.forEach((profile, index) => {
-            const bindings = isRecord(profile.bindings) ? profile.bindings : {};
-            const getTop = bindings.getTop ?? profile.getTopRva;
-            const type = bindings.type ?? profile.typeRva;
-            const rawLayout = isRecord(profile.stackLayout) ? profile.stackLayout : undefined;
-            if (getTop === undefined || (type === undefined && rawLayout === undefined))
-                return;
-            const normalizedBindings = {
-                getTop: normalizeHex(getTop, `abiProfiles[${index}].bindings.getTop`),
-                ...(type === undefined ? {} : { type: normalizeHex(type, `abiProfiles[${index}].bindings.type`) })
-            };
-            for (const key of ["toBoolean", "isInteger", "toInteger", "toNumber", "toLString", "toPointer", "toUserdata", "auxiliaryTypeName", "setTop", "pushNil", "next"]) {
-                if (bindings[key] !== undefined)
-                    normalizedBindings[key] = normalizeHex(bindings[key], `abiProfiles[${index}].bindings.${key}`);
-            }
-            profiles.push({
-                id: stringValue(profile.id) ?? `lua-abi-${index + 1}`,
-                buildKey,
-                status: ["confirmed", "dynamically_verified"].includes(stringValue(profile.status) ?? "") ? profile.status : "unresolved",
-                bindings: normalizedBindings,
-                ...(rawLayout ? {
-                    stackLayout: {
-                        basePointerOffset: boundedInteger(rawLayout.basePointerOffset, 0, 0, 0x1000, `abiProfiles[${index}].stackLayout.basePointerOffset`),
-                        topPointerOffset: boundedInteger(rawLayout.topPointerOffset, 0, 0, 0x1000, `abiProfiles[${index}].stackLayout.topPointerOffset`),
-                        slotSize: boundedInteger(rawLayout.slotSize, 0, 1, 0x1000, `abiProfiles[${index}].stackLayout.slotSize`),
-                        payloadOffset: boundedInteger(rawLayout.payloadOffset, 0, 0, 0x1000, `abiProfiles[${index}].stackLayout.payloadOffset`),
-                        tagOffset: boundedInteger(rawLayout.tagOffset, 0, 0, 0x1000, `abiProfiles[${index}].stackLayout.tagOffset`),
-                        tagSize: boundedInteger(rawLayout.tagSize, 2, 1, 4, `abiProfiles[${index}].stackLayout.tagSize`),
-                        ...(rawLayout.auxiliaryOffset === undefined ? {} : { auxiliaryOffset: boundedInteger(rawLayout.auxiliaryOffset, 0, 0, 0x1000, `abiProfiles[${index}].stackLayout.auxiliaryOffset`) }),
-                        maxSlots: boundedInteger(rawLayout.maxSlots, 8000, 1, 100000, `abiProfiles[${index}].stackLayout.maxSlots`)
-                    }
-                } : {}),
-                ...(isRecord(profile.typeTags) ? { typeTags: profile.typeTags } : {}),
-                ...(Array.isArray(profile.userdataProfiles) ? { userdataProfiles: profile.userdataProfiles } : {}),
-                ...(Array.isArray(profile.evidence) ? { evidence: profile.evidence } : {})
-            });
-        });
-        return profiles;
-    }
-    async loadCppCatalog(input, maxHooks) {
-        const callgraph = await this.readArtifact(input.buildKey, "lua-wrapper-callgraph");
-        const clusters = await this.readArtifactOptional(input.buildKey, "cpp-implementation-clusters") ?? {};
-        const targets = this.cppTargets(callgraph, clusters, input.buildKey);
-        if (targets.length === 0)
-            throw new Error("C++ callgraph contains no resolved trace targets");
-        const apis = new Set(normalizeApiList(input));
-        const rvas = new Set(normalizeRvaSelection(input.rva));
-        const clustersWanted = new Set((input.clusterIds ?? []).map((value, index) => requiredString(value, `clusterIds[${index}]`)));
-        const expression = input.glob === undefined ? undefined : globExpression(requiredString(input.glob, "glob"));
-        const selected = targets.filter(target => {
-            const aliases = arrayValue(target.aliases).filter((item) => typeof item === "string");
-            const namespaceMatch = input.namespace === undefined || aliases.some(api => api.startsWith(`${input.namespace}.`));
-            const apiMatch = apis.size === 0 || aliases.some(api => apis.has(api));
-            const globMatch = expression === undefined || aliases.some(api => expression.test(api));
-            const rvaMatch = rvas.size === 0 || rvas.has(String(target.rva));
-            const clusterMatch = clustersWanted.size === 0 || arrayValue(target.clusterIds).some(id => typeof id === "string" && clustersWanted.has(id));
-            return namespaceMatch && apiMatch && globMatch && rvaMatch && clusterMatch;
-        });
-        if (selected.length === 0)
-            throw new Error("C++ trace selection matched no indexed business targets");
-        if (selected.length > maxHooks)
-            throw new Error(`C++ trace selection resolved ${selected.length} targets, exceeding maxHooks=${maxHooks}`);
-        return { buildKey: input.buildKey, moduleName: normalizeModuleName(callgraph.module, this.moduleName), targets: selected };
-    }
-    cppTargets(callgraph, clusters, buildKey) {
-        const byRva = new Map();
-        const add = (rvaValue, api, clusterId) => {
-            if (rvaValue === undefined || rvaValue === null)
-                return;
-            let rva;
-            try {
-                rva = normalizeHex(rvaValue, "business callee RVA");
-            }
-            catch {
-                return;
-            }
-            const rvaNumber = hexToNumber(rva, "business callee RVA");
-            const existing = byRva.get(rva) ?? { id: `${buildKey}:cpp:${rva}`, rva, rvaNumber, aliases: [], clusterIds: [] };
-            const aliases = existing.aliases;
-            if (api && !aliases.includes(api))
-                aliases.push(api);
-            const clusterIds = existing.clusterIds;
-            if (clusterId && !clusterIds.includes(clusterId))
-                clusterIds.push(clusterId);
-            byRva.set(rva, existing);
-        };
-        for (const record of recordsFrom(callgraph, ["records", "wrappers"])) {
-            const namespace = stringValue(record.namespace) ?? "global";
-            const name = stringValue(record.name ?? record.apiName);
-            const api = stringValue(record.api) ?? (name ? `${namespace}.${name}` : undefined);
-            add(pickPath(record, [
-                ["firstBusinessCalleeRva"], ["businessCalleeRva"], ["businessEntryRva"],
-                ["firstBusinessCallee", "rva"], ["firstNonLuaBusinessCallee", "rva"], ["businessEntry", "rva"]
-            ]), api, stringValue(record.implementationClusterId ?? record.clusterId));
-        }
-        for (const cluster of recordsFrom(clusters, ["clusters", "records"])) {
-            const clusterId = stringValue(cluster.clusterId ?? cluster.id);
-            const rva = pickPath(cluster, [["businessEntryRva"], ["entryRva"], ["businessEntry", "rva"]]);
-            const wrappers = arrayValue(cluster.wrappers ?? cluster.apis ?? cluster.APIs);
-            if (wrappers.length === 0)
-                add(rva, undefined, clusterId);
-            for (const wrapper of wrappers) {
-                if (typeof wrapper === "string")
-                    add(rva, wrapper, clusterId);
-                else if (isRecord(wrapper)) {
-                    const namespace = stringValue(wrapper.namespace) ?? "global";
-                    const name = stringValue(wrapper.name);
-                    add(rva, stringValue(wrapper.api) ?? (name ? `${namespace}.${name}` : undefined), clusterId);
-                }
-            }
-        }
-        return [...byRva.values()];
-    }
-    signatureRecords(profile) {
-        const records = [];
-        const visit = (value, depth) => {
-            if (depth > 4)
-                return;
-            if (Array.isArray(value)) {
-                for (const item of value)
-                    visit(item, depth + 1);
-                return;
-            }
-            if (!isRecord(value))
-                return;
-            const hasRva = value.rva !== undefined || value.entryRva !== undefined;
-            const hasPattern = value.entryBytesHex !== undefined || value.bytesHex !== undefined || value.signature !== undefined || value.aob !== undefined;
-            if (hasRva && hasPattern)
-                records.push(value);
-            for (const [key, child] of Object.entries(value)) {
-                if (["staticEvidence", "liveEvidence", "evidence", "inputs", "outputs"].includes(key))
-                    continue;
-                if (typeof child === "object" && child !== null)
-                    visit(child, depth + 1);
-            }
-        };
-        visit(profile.signatures ?? profile.functions ?? profile.buildSignatures ?? profile, 0);
-        const seen = new Set();
-        return records.filter(record => {
-            const key = `${String(record.rva ?? record.entryRva)}:${String(record.entryBytesHex ?? record.bytesHex ?? record.signature ?? record.aob)}`;
-            if (seen.has(key))
-                return false;
-            seen.add(key);
-            return true;
-        });
-    }
-    async verifySignature(target, signature, index) {
-        try {
-            const rva = normalizeHex(signature.rva ?? signature.entryRva, `signature[${index}].rva`);
-            const offset = hexToNumber(rva, `signature[${index}].rva`);
-            const patternValue = requiredString(signature.entryBytesHex ?? signature.bytesHex ?? signature.signature ?? signature.aob, `signature[${index}].pattern`);
-            const tokens = patternValue.includes(" ") ? patternValue.trim().split(/\s+/) : patternValue.match(/.{1,2}/g) ?? [];
-            if (tokens.length === 0 || tokens.length > 256 || tokens.some(token => !/^(?:[0-9a-f]{2}|\?\?)$/i.test(token))) {
-                throw new Error("signature pattern must contain byte or ?? tokens and be at most 256 bytes");
-            }
-            if (offset + tokens.length > target.moduleSize)
-                throw new Error("signature exceeds module range");
-            const address = hexAdd(target.moduleBase, rva);
-            const read = await this.executor.execute({ operation: "read_memory", sessionId: target.sessionId, address, size: tokens.length }, target.context);
-            const actualHex = requiredString(read.bytesHex, "read_memory.bytesHex").toLowerCase();
-            const actual = actualHex.match(/.{1,2}/g) ?? [];
-            const passed = tokens.every((token, tokenIndex) => token === "??" || token.toLowerCase() === actual[tokenIndex]);
-            return { name: stringValue(signature.name ?? signature.id) ?? `signature_${index}`, rva, runtimeAddress: address, expected: tokens.join(" "), actual: actual.join(" "), passed };
-        }
-        catch (error) {
-            return { name: stringValue(signature.name ?? signature.id) ?? `signature_${index}`, passed: false, error: errorText(error) };
-        }
-    }
-    statusCounts(records, preferredKey = "status") {
-        const counts = {};
-        for (const record of records) {
-            const status = statusValue(record, preferredKey, "status", "resolutionStatus", "readerStatus") ?? "unresolved";
-            counts[status] = (counts[status] ?? 0) + 1;
-        }
-        return { total: records.length, statuses: counts };
-    }
-}
-function errorText(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-export function createWowAnalysisService(options) {
-    return new WowAnalysisService(options);
-}