rea-agents 6.4.0 → 6.7.0

package/dist/kuna/KunaSessionClient.js

@@ -0,0 +1,1162 @@
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { z } from "zod";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { analysisSearchPredicate, analysisSearchQuerySchema, } from "../domain/analysisSearch.js";
+import { combineFunctionRelationshipCoverage } from "../domain/functionCallCoverage.js";
+import { functionDossierSchema } from "../domain/hopperValues.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { ABORTED, waitForAbortable } from "../process/AbortablePromise.js";
+import { SharedStartupAttempt } from "../process/SharedStartupAttempt.js";
+import { KUNA_INVENTORY_OUTPUT_BYTES, kunaFileCleanupError, } from "./KunaCommand.js";
+import { kunaFunctionDeadline } from "./KunaConfiguration.js";
+import { createKunaFileCloseScope, inspectKunaInstallation, } from "./KunaInstallation.js";
+import { kunaProjectKey, } from "./KunaProjectCache.js";
+import { parseKunaInventory, } from "./KunaProjectFiles.js";
+import { isKunaOperation, KUNA_RELATIONSHIP_LIMITATION, KUNA_SINGLE_FUNCTION_LIMITATION, kunaLimitations, } from "./KunaProviderCapabilities.js";
+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";
+import { KunaTargetCommands } from "./KunaTargetCommands.js";
+import { KunaReferenceQueries } from "./KunaReferenceQueries.js";
+import { KunaQueryWork } from "./KunaQueryWork.js";
+import { KunaStringQueries } from "./KunaStringQueries.js";
+import { normalizeKunaAddress } from "./KunaAddress.js";
+import { KUNA_FUNCTION_TEXT_BYTES } from "./KunaLimits.js";
+import { KunaProjectReader, } from "./KunaProjectReader.js";
+import { kunaUnavailable } from "./KunaUnavailable.js";
+import { RegularFileCleanupFailure, regularFileCancellation, } from "../filesystem/OwnedRegularFile.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { kunaQueryFailureForCaller } from "./KunaQueryErrors.js";
+/** How often a request waiting on the project export reports that it still waits. */
+const WAIT_PROGRESS_INTERVAL_MS = 10_000;
+/** A queued single-function request found the export finished first. */
+const EXPORT_READY = Symbol("kuna-export-ready");
+/**
+ * Completed single-function texts a session keeps while it has no export
+ * reader. Each repeat would otherwise analyze the whole image again; after a
+ * failed export that holds for the rest of the session.
+ */
+const SINGLE_FUNCTION_TEXT_CACHE_BYTES = 16 * 1024 * 1024;
+/** Charged per kept text beside its UTF-8 bytes. */
+const SINGLE_FUNCTION_TEXT_ENTRY_BYTES = 256;
+/**
+ * Wait for work this session owns, stopping only this caller's wait when its
+ * signal aborts; the work itself continues for other callers.
+ */
+const waitFor = async (work, signal, operation) => {
+    const result = await waitForAbortable(work, signal);
+    return result === ABORTED
+        ? err(new AnalysisCancelledError(operation, { cause: signal?.reason }))
+        : result;
+};
+/** A file the adopted export named is gone, e.g. evicted by another REA process. */
+const isMissing = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    (cause.code === "ENOENT" || cause.code === "ENOTDIR");
+/** Read through a call so a check before an await does not narrow later ones. */
+const cancelled = (signal) => signal?.aborted === true;
+const message = (cause) => cause instanceof Error ? cause.message : String(cause);
+const failure = (operation, cause) => cause instanceof AnalysisError
+    ? cause
+    : new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {
+        cause,
+        userMessage: `Kuna ${operation} failed: ${message(cause)}`,
+    });
+/**
+ * How a request that needs the export reports the export's failure. A session
+ * never rebuilds a failed export, so repeating the request cannot succeed; the
+ * error says what to change before reopening the target. Kuna settings are read
+ * when REA starts, so changing one also needs a restart. Cancellation and
+ * unproven cleanup keep their own errors, which callers must still observe.
+ */
+const exportUnavailable = (operation, failure) => {
+    if (failure instanceof AnalysisCancelledError || failure.cleanupIncomplete)
+        return failure;
+    const reason = failure.userMessage ?? failure.message;
+    const exported = projectAnalysisError(failure);
+    const restart = "REA reads Kuna settings when it starts, so restart REA, then reopen the target.";
+    const next = failure instanceof AnalysisTimeoutError
+        ? `To retry, set REA_KUNA_PROJECT_TIMEOUT_MS above ${String(failure.timeoutMs)} ms or raise REA_KUNA_JOBS in the environment that starts REA. ${restart}`
+        : failure instanceof AnalysisResourceConstraintError &&
+            failure.remediationAction !== undefined
+            ? // A fixed buffer (`memory`) is no setting, so a restart cannot help.
+                `${failure.remediationAction.replace(/\.?$/u, ".")}${failure.resource === "memory" ? "" : ` ${restart}`}`
+            : "To retry, resolve the reported failure, then reopen the target.";
+    return new AnalysisCapabilityUnavailableError(KUNA_PROVIDER_ID, operation, reason, {
+        cause: failure,
+        // Callers see only the top-level projection, so the export failure's
+        // own projected code and details (its limits, target path, captured
+        // output and diagnostics) travel whole rather than field by field.
+        diagnostics: {
+            export_error: failure._tag,
+            export_code: exported.code,
+            ...(exported.details === undefined
+                ? {}
+                : { export_details: exported.details }),
+        },
+        userMessage: `Kuna's project export failed, so ${operation} is unavailable in this session: ${reason.replace(/\.?$/u, ".")} ${next}`,
+    });
+};
+/** Kuna names a procedure by its inventory entry or by an exact entry address. */
+const procedureSelectorSchema = z.string().min(1);
+/**
+ * One Kuna analysis session for one target.
+ *
+ * Reads come from the verified project export in REA's cache. Until that
+ * export exists, listings use the inventory the export takes first and
+ * pseudocode a single-function `kuna decompile`, while the export builds in
+ * the background; assembly waits for it. Kuna always runs on a private copy
+ * whose digest matches the selected target.
+ */
+export class KunaSessionClient {
+    #target;
+    #profile;
+    #cache;
+    #environment;
+    #runSlots;
+    #fileCloseResources = new ArtifactResourceScope();
+    /** Single-function runs in flight, by entry address. */
+    #singleFunctionRuns = new Map();
+    /** Completed single-function texts by address, least recently used first. */
+    #singleFunctionTexts = new Map();
+    #singleFunctionTextBytes = 0;
+    /** Owns background work: aborting it cancels this session's export interest. */
+    #session = new AbortController();
+    /** Requests and shared readers retain their resources until their work settles. */
+    #active = new Set();
+    #commands;
+    #queryWork;
+    #references;
+    #strings;
+    #installation;
+    #inventory;
+    #project;
+    /** The cache lookup that decides #project, shared by concurrent first requests. */
+    #starting;
+    /** The building export's inventory; undefined when it settles without one. */
+    #exportInventory;
+    #reader;
+    #inventoryIndex;
+    #status;
+    #key;
+    #exportFailure;
+    #releasePin;
+    /** Set once close starts; new requests are refused from then on. */
+    #closing = false;
+    /** Set only when close has released every owned resource. */
+    #closed = false;
+    constructor(target, profile, dependencies) {
+        this.#target = target;
+        this.#profile = profile;
+        this.#cache = dependencies.cache;
+        this.#runSlots = dependencies.runSlots;
+        this.#environment = dependencies.environment;
+        this.#commands = new KunaTargetCommands(target, {
+            signal: this.#session.signal,
+            ...(dependencies.launcher === undefined
+                ? {}
+                : { launcher: dependencies.launcher }),
+        });
+        this.#queryWork = new KunaQueryWork(this.#commands, {
+            signal: this.#session.signal,
+            own: (work) => this.#own(work),
+            runSlots: dependencies.runSlots,
+        });
+        this.#references = new KunaReferenceQueries(this.#queryWork);
+        this.#strings = new KunaStringQueries(this.#queryWork);
+    }
+    async execute(operation, parameters, options = {}) {
+        if (this.#closing)
+            return err(kunaUnavailable(operation, "This Kuna session is closed."));
+        return this.#own(this.#execute(operation, parameters, {
+            ...options,
+            signal: options.signal === undefined
+                ? this.#session.signal
+                : AbortSignal.any([this.#session.signal, options.signal]),
+        }));
+    }
+    #own(work) {
+        this.#active.add(work);
+        const release = () => this.#active.delete(work);
+        void work.then(release, release);
+        return work;
+    }
+    async #execute(operation, parameters, options) {
+        if (cancelled(options.signal))
+            return err(new AnalysisCancelledError(operation, {
+                cause: options.signal?.reason,
+            }));
+        if (operation !== "health" && !isKunaOperation(operation))
+            return err(kunaUnavailable(operation, "Kuna answers procedure and string queries, pseudocode, assembly and references; this operation needs another provider."));
+        const document = parameters.document;
+        if (document !== undefined && document !== this.#target.path)
+            return err(new AnalysisInputError(operation, {
+                userMessage: "A Kuna session analyzes one program; omit document or pass the selected target path.",
+            }, [
+                {
+                    path: ["document"],
+                    reason: "invalid_value",
+                    expected: this.#target.path,
+                },
+            ]));
+        const installation = await this.#ensureInstallation(operation, options.signal);
+        if (!installation.ok)
+            return installation;
+        try {
+            if (operation === "health")
+                return ok(this.#execution([], installation.value, {
+                    result: {
+                        ready: true,
+                        kuna: {
+                            version: installation.value.version,
+                            verified: installation.value.verified,
+                            sha256: installation.value.sha256,
+                        },
+                    },
+                    source: null,
+                    locations: [],
+                    limitations: [],
+                }));
+            if (operation === "procedure_pseudo_code" ||
+                operation === "procedure_assembly" ||
+                operation === "analyze_function")
+                await this.#startProject(installation.value);
+            const answer = await this.#answer(operation, parameters, installation.value, options);
+            if (!answer.ok)
+                return err(kunaQueryFailureForCaller(answer.error, operation));
+            if (cancelled(options.signal))
+                return err(new AnalysisCancelledError(operation, {
+                    cause: options.signal?.reason,
+                }));
+            return ok(this.#execution(kunaLimitations(operation), installation.value, answer.value));
+        }
+        catch (cause) {
+            if (cancelled(options.signal))
+                return err(new AnalysisCancelledError(operation, { cause }));
+            return err(failure(operation, cause));
+        }
+    }
+    /**
+     * Release everything this session owns. A failed close keeps reporting its
+     * failure, and each later call retries the cleanup that remains.
+     */
+    async close() {
+        if (this.#closed)
+            return ok(null);
+        if (!this.#closing) {
+            this.#closing = true;
+            this.#session.abort();
+        }
+        // Cancellation starts process shutdown; its completion proves whether it
+        // is safe to remove private copies and exposes any retained cleanup owner.
+        // An admitted request may create a shared reader after shutdown begins.
+        while (this.#active.size > 0)
+            await Promise.allSettled(this.#active);
+        this.#references.clear();
+        this.#strings.clear();
+        this.#dropSingleFunctionTexts();
+        await this.#project;
+        await this.#inventory;
+        const failures = [];
+        // Kuna runs in its own process group; an export no other session wants
+        // must stop before this session reports itself closed.
+        if (this.#key !== undefined) {
+            const settled = await this.#cache.settled(this.#key);
+            if (!settled.ok)
+                failures.push(settled.error);
+        }
+        const commands = await this.#commands.close();
+        if (!commands.ok)
+            failures.push(commands.error);
+        try {
+            await this.#fileCloseResources.close();
+        }
+        catch (cause) {
+            const observation = ArtifactReaderFailure.cleanupObservation(cause, "Kuna provider file descriptor");
+            failures.push(new ProviderCleanupError(KUNA_PROVIDER_ID, observation.resources, { reason: observation.reason }, { cause, operation: "close_binary" }));
+        }
+        if (failures.length > 0)
+            return err(new ProviderCleanupError(KUNA_PROVIDER_ID, failures.flatMap((failed) => failed.cleanupResources), {
+                reason: failures
+                    .map((failed) => String(failed.diagnostics?.["reason"] ?? failed.message))
+                    .join("; "),
+            }, {
+                cause: new AggregateError(failures, "Kuna session cleanup remains incomplete"),
+                operation: "close_binary",
+            }).bindCleanupDependencies(failures));
+        this.#releasePin?.();
+        this.#releasePin = undefined;
+        this.#closed = true;
+        return ok(null);
+    }
+    #execution(operationLimitations, installation, answer) {
+        const source = answer.source;
+        const files = source?.kind !== "project-export"
+            ? []
+            : (answer.files ?? []).map((file) => ({
+                facet: file.facet,
+                file: file.path,
+                file_sha256: Object.values(source.project.manifest.files).find(({ path }) => path === file.path)?.sha256 ?? null,
+                byte_offset: file.byteOffset,
+                byte_length: file.byteLength,
+            }));
+        // Preserve the direct text source shape; combined answers retain every
+        // component once, including its producing file digest and byte range.
+        const recordedFiles = files.length === 1 ? files[0] : files.length === 0 ? {} : { files };
+        return createAnalysisExecution(answer.result, {
+            id: KUNA_PROVIDER_ID,
+            name: "Kuna",
+            version: installation.version,
+        }, {
+            // Kuna's identity is in the analysis profile; the raw result records
+            // only where file-backed text came from.
+            ...(source === null &&
+                answer.referenceSource === undefined &&
+                answer.stringSource === undefined
+                ? {}
+                : {
+                    rawResult: {
+                        ...(source === null
+                            ? {}
+                            : {
+                                source: source.kind === "single-function"
+                                    ? { kind: "single-function" }
+                                    : {
+                                        kind: "project-export",
+                                        key: source.project.key,
+                                        directory: source.project.directory,
+                                        ...recordedFiles,
+                                    },
+                                project_export: this.#exportState(),
+                            }),
+                        ...(answer.referenceSource === undefined
+                            ? {}
+                            : { references: answer.referenceSource }),
+                        ...(answer.stringSource === undefined
+                            ? {}
+                            : { strings: answer.stringSource }),
+                    },
+                }),
+            limitations: [...operationLimitations, ...answer.limitations],
+            ...(answer.relationshipCoverage === undefined
+                ? {}
+                : { relationshipCoverage: answer.relationshipCoverage }),
+            locations: [
+                { kind: "artifact-path", path: this.#target.path },
+                ...answer.locations,
+            ],
+            ...(this.#profile === undefined
+                ? {}
+                : { analysisProfile: this.#profile }),
+        });
+    }
+    /** Where the background export stands, for callers deciding whether to wait. */
+    #exportState() {
+        if (this.#reader !== undefined)
+            return { state: "ready", key: this.#reader.project.key };
+        if (this.#project === undefined)
+            return { state: "not-started" };
+        if (this.#exportFailure !== undefined)
+            return { state: "failed", reason: this.#exportFailure };
+        return {
+            state: "building",
+            phase: this.#status?.phase ?? null,
+            inventory_functions: this.#status?.inventory?.length ?? null,
+        };
+    }
+    async #answer(operation, parameters, installation, options) {
+        if (operation === "list_documents")
+            return ok({
+                result: [this.#target.path],
+                source: null,
+                locations: [],
+                limitations: [],
+            });
+        if (operation === "xrefs" ||
+            operation === "procedure_callers" ||
+            operation === "procedure_callees")
+            return this.#referenceAnswer(operation, parameters, installation, options);
+        if (operation === "list_strings" || operation === "search_strings")
+            return this.#stringAnswer(operation, parameters, installation, options);
+        if (operation === "list_procedures" || operation === "search_procedures")
+            return this.#procedureList(operation, parameters, installation, options);
+        const inventory = await this.#ensureInventory(installation, options);
+        if (!inventory.ok)
+            return inventory;
+        if (operation === "address_name")
+            return this.#addressName(parameters, inventory.value, installation, options);
+        const entry = this.#resolve(operation, parameters.procedure, inventory.value);
+        if (!entry.ok) {
+            const selectedAddress = operation === "procedure_address"
+                ? normalizeKunaAddress(parameters.procedure)
+                : undefined;
+            if (selectedAddress === undefined)
+                return entry;
+            const graph = await this.#references.functionAt(installation, selectedAddress, operation, options.signal);
+            if (!graph.ok)
+                return graph;
+            if (graph.value === undefined)
+                return entry;
+            return ok({
+                result: graph.value.address,
+                source: null,
+                locations: [{ kind: "address", address: selectedAddress }],
+                limitations: [],
+                referenceSource: graph.value.source,
+            });
+        }
+        const locations = [
+            { kind: "address", address: entry.value.address },
+        ];
+        switch (operation) {
+            case "procedure_address":
+                return ok({
+                    result: entry.value.address,
+                    source: null,
+                    locations,
+                    limitations: [],
+                });
+            case "procedure_pseudo_code": {
+                const pseudocode = await this.#pseudocode(operation, entry.value, installation, options);
+                if (!pseudocode.ok)
+                    return pseudocode;
+                return ok({ ...pseudocode.value, locations });
+            }
+            case "procedure_assembly": {
+                const assembly = await this.#assemblyText(operation, entry.value, installation, options);
+                if (!assembly.ok)
+                    return assembly;
+                return ok({ ...assembly.value, locations });
+            }
+            case "analyze_function":
+                return this.#withProject(operation, installation, options, (reader) => this.#dossier(operation, entry.value, reader, installation, options.signal));
+        }
+    }
+    async #stringAnswer(operation, parameters, installation, options) {
+        const answer = await this.#own(this.#strings.execute(operation, parameters, installation, AbortSignal.any([
+            this.#session.signal,
+            ...(options.signal === undefined ? [] : [options.signal]),
+        ])));
+        return answer.ok
+            ? ok({
+                result: answer.value.result,
+                source: null,
+                stringSource: answer.value.source,
+                locations: [],
+                limitations: [],
+            })
+            : answer;
+    }
+    async #procedureList(operation, parameters, installation, options) {
+        const query = operation === "search_procedures"
+            ? analysisSearchQuerySchema.safeParse(parameters)
+            : undefined;
+        if (query !== undefined && !query.success)
+            return err(analysisInputErrorFromIssues(operation, query.error.issues, parameters));
+        const inventory = await this.#ensureInventory(installation, options);
+        if (!inventory.ok)
+            return inventory;
+        let selected = inventory.value;
+        if (query?.success === true) {
+            if (query.data.mode === "regex") {
+                const matches = await this.#queryWork.match({
+                    operation,
+                    pattern: query.data.pattern,
+                    caseSensitive: query.data.case_sensitive,
+                    values: () => inventory.value.map(({ name }) => name),
+                    signal: options.signal,
+                });
+                if (!matches.ok)
+                    return matches;
+                selected = matches.value.map((index) => inventory.value[index]);
+            }
+            else {
+                const matches = analysisSearchPredicate(query.data);
+                selected = inventory.value.filter(({ name }) => matches(name));
+            }
+        }
+        return ok({
+            result: selected.map(({ address, name }) => ({ address, value: name })),
+            source: null,
+            locations: [],
+            limitations: [],
+        });
+    }
+    async #referenceAnswer(operation, parameters, installation, options) {
+        const field = operation === "xrefs" ? "address" : "procedure";
+        const selected = await this.#referenceAddress(operation, parameters[field], field, installation, options);
+        if (!selected.ok)
+            return selected;
+        const address = selected.value;
+        const locations = [{ kind: "address", address }];
+        if (operation === "xrefs") {
+            const references = await this.#references.incoming(installation, address, options.signal);
+            if (!references.ok)
+                return references;
+            return ok({
+                result: [...references.value.addresses],
+                source: null,
+                locations,
+                limitations: [],
+                referenceSource: {
+                    kind: "kuna-xrefs",
+                    direction: "to",
+                    target: address,
+                    sha256: references.value.sha256,
+                    bytes: references.value.bytes,
+                    examined_rows: references.value.rows,
+                    excluded_alias_rows: references.value.excludedAliasRows,
+                },
+            });
+        }
+        const relationships = await this.#references.relationships(installation, address, operation, options.signal);
+        if (!relationships.ok)
+            return relationships;
+        const entries = operation === "procedure_callers"
+            ? relationships.value.callers
+            : relationships.value.callees;
+        return ok({
+            result: entries.map(({ address }) => address),
+            source: null,
+            locations,
+            referenceSource: relationships.value.source,
+            limitations: [],
+            relationshipCoverage: operation === "procedure_callers"
+                ? relationships.value.callersCoverage
+                : relationships.value.calleesCoverage,
+        });
+    }
+    /** Exact addresses are validated by the producing graph, which also owns
+     * synthetic import nodes absent from the quick function inventory. */
+    async #referenceAddress(operation, raw, field, installation, options) {
+        if (typeof raw !== "string" || raw.length === 0)
+            return err(new AnalysisInputError(operation, { userMessage: `Kuna requires ${field}; it has no cursor.` }, [{ path: [field], reason: "missing_argument" }]));
+        const address = normalizeKunaAddress(raw);
+        if (address !== undefined)
+            return ok(address);
+        if (/^0x[0-9a-f]+$/iu.test(raw))
+            return err(new AnalysisInputError(operation, { userMessage: "The address exceeds Kuna's u64 address space." }, [{ path: [field], reason: "invalid_value" }]));
+        const inventory = await this.#ensureInventory(installation, options);
+        if (!inventory.ok)
+            return inventory;
+        const entry = this.#resolve(operation, raw, inventory.value, field);
+        return entry.ok ? ok(entry.value.address) : entry;
+    }
+    /** Resolve an exact inventory name, alias or entry address. */
+    #resolve(operation, raw, inventory, field = "procedure") {
+        const parsed = procedureSelectorSchema.safeParse(raw);
+        if (!parsed.success)
+            return err(new AnalysisInputError(operation, { userMessage: `${field} is required.` }, [{ path: [field], reason: "missing_argument" }]));
+        const selector = parsed.data;
+        const address = normalizeKunaAddress(selector);
+        if (address !== undefined) {
+            const entry = this.#index(inventory).byAddress.get(address);
+            return entry === undefined
+                ? err(new AnalysisInputError(operation, {
+                    userMessage: `${address} is not a procedure entry Kuna found; list_procedures shows the entries it found.`,
+                }))
+                : ok(entry);
+        }
+        const matches = this.#index(inventory).byName.get(selector) ?? [];
+        if (matches.length === 1 && matches[0] !== undefined)
+            return ok(matches[0]);
+        return err(new AnalysisInputError(operation, {
+            userMessage: matches.length === 0
+                ? `Kuna found no procedure named ${selector}; search_procedures finds similar names.`
+                : `${selector} names ${String(matches.length)} Kuna entries (${matches.map(({ address }) => address).join(", ")}); select one by address.`,
+        }));
+    }
+    async #addressName(parameters, inventory, installation, options) {
+        const raw = parameters.address;
+        const address = normalizeKunaAddress(raw);
+        if (address === undefined)
+            return err(new AnalysisInputError("address_name", {
+                userMessage: "Kuna has no cursor; pass an explicit 0x-prefixed address.",
+            }, [{ path: ["address"], reason: "invalid_format" }]));
+        const locations = [{ kind: "address", address }];
+        const entry = this.#index(inventory).byAddress.get(address);
+        if (entry !== undefined)
+            return ok({
+                result: entry.name,
+                source: null,
+                locations,
+                limitations: [],
+            });
+        await this.#startProject(installation);
+        return this.#withProject("address_name", installation, options, async (reader) => {
+            const name = await reader.dataName(address, "address_name", options.signal);
+            if (!name.ok)
+                return name;
+            return ok({
+                result: name.value,
+                source: { kind: "project-export", project: reader.project },
+                locations,
+                limitations: [
+                    "Kuna names function entries and the data its export references; null means Kuna assigned no name at this address, not that no symbol exists.",
+                ],
+            });
+        });
+    }
+    async #pseudocode(operation, entry, installation, options) {
+        for (let recovered = false;;) {
+            const reader = this.#reader;
+            if (reader !== undefined) {
+                try {
+                    const text = await reader.pseudocode(entry.address, operation);
+                    if (!text.ok)
+                        return text;
+                    return ok({
+                        ...text.value,
+                        source: { kind: "project-export", project: reader.project },
+                    });
+                }
+                catch (cause) {
+                    if (!isMissing(cause) || recovered)
+                        throw cause;
+                    recovered = true;
+                    this.#invalidateProject(reader);
+                    await this.#startProject(installation);
+                    continue;
+                }
+            }
+            const outcome = await this.#joinSingleFunction(operation, entry.address, installation, options.signal);
+            if (outcome === EXPORT_READY)
+                continue;
+            if (!outcome.ok)
+                return outcome;
+            const exportFailure = await this.#settledExportFailure();
+            return ok({
+                result: outcome.value,
+                source: { kind: "single-function" },
+                limitations: [
+                    KUNA_SINGLE_FUNCTION_LIMITATION,
+                    ...(exportFailure === undefined
+                        ? []
+                        : [
+                            `The project export failed, so later requests also use single-function runs: ${exportFailure}`,
+                        ]),
+                ],
+            });
+        }
+    }
+    /**
+     * Wait for this address's shared single-function run, starting it when none
+     * is in flight. A caller's cancellation stops only its own wait while others
+     * still wait; the last waiter stops the run and receives how it ended,
+     * including cleanup it could not prove. A completed text answers repeats
+     * until the export can.
+     */
+    #joinSingleFunction(operation, address, installation, signal) {
+        if (cancelled(signal))
+            return Promise.resolve(err(new AnalysisCancelledError(operation, { cause: signal?.reason })));
+        const kept = this.#singleFunctionTexts.get(address);
+        if (kept !== undefined) {
+            this.#singleFunctionTexts.delete(address);
+            this.#singleFunctionTexts.set(address, kept);
+            return Promise.resolve(ok(kept.text));
+        }
+        let run = this.#singleFunctionRuns.get(address);
+        if (run === undefined) {
+            const controller = new AbortController();
+            const created = {
+                controller,
+                waiters: 0,
+                outcome: this.#own(this.#singleFunction(operation, address, installation, AbortSignal.any([this.#session.signal, controller.signal])).catch((cause) => err(failure(operation, cause)))),
+            };
+            this.#singleFunctionRuns.set(address, created);
+            void created.outcome.then((outcome) => {
+                // A run whose waiters all left was already replaced or removed.
+                if (this.#singleFunctionRuns.get(address) !== created)
+                    return;
+                this.#singleFunctionRuns.delete(address);
+                if (outcome !== EXPORT_READY && outcome.ok)
+                    this.#keepSingleFunctionText(address, outcome.value);
+            });
+            run = created;
+        }
+        const shared = run;
+        shared.waiters += 1;
+        return new Promise((resolve) => {
+            let waiting = true;
+            const leave = () => {
+                waiting = false;
+                shared.waiters -= 1;
+            };
+            const onAbort = () => {
+                if (!waiting)
+                    return;
+                leave();
+                if (shared.waiters > 0) {
+                    resolve(err(new AnalysisCancelledError(operation, { cause: signal?.reason })));
+                    return;
+                }
+                // A run whose waiters all left winds down; a new request starts afresh.
+                if (this.#singleFunctionRuns.get(address) === shared)
+                    this.#singleFunctionRuns.delete(address);
+                shared.controller.abort(signal?.reason);
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            void shared.outcome.then((outcome) => {
+                signal?.removeEventListener("abort", onAbort);
+                if (waiting)
+                    leave();
+                resolve(outcome);
+            });
+        });
+    }
+    /** Keep a completed text within budget, dropping the least recently used. */
+    #keepSingleFunctionText(address, text) {
+        // The export's text supersedes it; a closing session keeps nothing.
+        if (this.#reader !== undefined || this.#closing)
+            return;
+        const bytes = Buffer.byteLength(text) + SINGLE_FUNCTION_TEXT_ENTRY_BYTES;
+        if (bytes > SINGLE_FUNCTION_TEXT_CACHE_BYTES)
+            return;
+        this.#singleFunctionTexts.set(address, { text, bytes });
+        this.#singleFunctionTextBytes += bytes;
+        while (this.#singleFunctionTextBytes > SINGLE_FUNCTION_TEXT_CACHE_BYTES) {
+            const oldest = this.#singleFunctionTexts.entries().next().value;
+            if (oldest === undefined)
+                break;
+            this.#singleFunctionTexts.delete(oldest[0]);
+            this.#singleFunctionTextBytes -= oldest[1].bytes;
+        }
+    }
+    #dropSingleFunctionTexts() {
+        this.#singleFunctionTexts.clear();
+        this.#singleFunctionTextBytes = 0;
+    }
+    /** One `kuna decompile --addr` run, admitted by the provider's run slots. */
+    async #singleFunction(operation, address, installation, signal) {
+        const prepared = await this.#commands.prepare();
+        if (!prepared.ok)
+            return prepared;
+        const admitted = await this.#admitSingleFunction(signal);
+        if (admitted === EXPORT_READY)
+            return admitted;
+        if (admitted === undefined)
+            return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
+        const run = await this.#commands.run({
+            installation,
+            arguments: (input) => ["decompile", input, address, "--addr"],
+            operation,
+            deadline: kunaFunctionDeadline(installation.configuration),
+            outputBytes: KUNA_FUNCTION_TEXT_BYTES,
+            signal,
+            releaseRun: admitted,
+        });
+        return run.ok ? ok(run.value.stdout.text.replace(/\n+$/u, "")) : run;
+    }
+    /**
+     * A run slot, or EXPORT_READY when the export this session builds finishes
+     * first; the export then answers without another Kuna process.
+     */
+    async #admitSingleFunction(signal) {
+        const yielded = new AbortController();
+        const slot = this.#runSlots.acquire(AbortSignal.any([signal, yielded.signal]));
+        const project = this.#project;
+        const exported = project === undefined
+            ? undefined
+            : project.then((built) => built.ok && this.#reader !== undefined
+                ? EXPORT_READY
+                : new Promise(() => undefined));
+        const admitted = await (exported === undefined
+            ? slot
+            : Promise.race([slot, exported]));
+        if (admitted !== EXPORT_READY)
+            return admitted;
+        yielded.abort();
+        // A slot granted in the same turn is returned rather than leaked.
+        void slot.then((release) => release?.());
+        return EXPORT_READY;
+    }
+    async #assemblyText(operation, entry, installation, options) {
+        return this.#withProject(operation, installation, options, async (reader) => {
+            const text = await reader.assembly(entry.address, operation, options.signal);
+            return text.ok
+                ? ok({
+                    ...text.value,
+                    source: { kind: "project-export", project: reader.project },
+                })
+                : text;
+        });
+    }
+    async #dossier(operation, entry, reader, installation, signal) {
+        const assembly = await reader.assembly(entry.address, operation, signal);
+        if (!assembly.ok)
+            return assembly;
+        const pseudocode = await reader.pseudocode(entry.address, operation);
+        if (!pseudocode.ok)
+            return pseudocode;
+        const text = typeof pseudocode.value.result === "string"
+            ? pseudocode.value.result
+            : null;
+        const unavailable = (reason) => ({ available: false, reason });
+        const relationships = await this.#references.relationships(installation, entry.address, operation, signal);
+        if (!relationships.ok &&
+            (relationships.error.cleanupIncomplete || signal?.aborted === true))
+            return relationships;
+        const callAvailability = relationships.ok
+            ? { available: true }
+            : unavailable(relationships.error.userMessage ?? relationships.error.message);
+        const dossier = functionDossierSchema.parse({
+            procedure: {
+                address: entry.address,
+                name: entry.name,
+                classification: null,
+                body: unavailable("Kuna reports an inventory extent that is an upper bound, not observed body ranges."),
+                signature: null,
+                locals: [],
+            },
+            pseudocode: text ?? "",
+            assembly: typeof assembly.value.result === "string"
+                ? assembly.value.result.split("\n")
+                : [],
+            comments: [],
+            callers: relationships.ok ? relationships.value.callers : [],
+            callees: relationships.ok ? relationships.value.callees : [],
+            incoming_references: [],
+            outgoing_references: [],
+            referenced_strings: [],
+            referenced_names: [],
+            basic_blocks: [],
+            native_api: null,
+            native_value_flow: null,
+            facet_availability: {
+                pseudocode: text === null
+                    ? unavailable(pseudocode.value.limitations.at(-1) ??
+                        "Kuna did not supply pseudocode.")
+                    : { available: true },
+                assembly: { available: true },
+                comments: unavailable("Kuna exports no analyst comments."),
+                callers: callAvailability,
+                callees: callAvailability,
+                references: unavailable("This provider does not report typed references."),
+                strings_names: unavailable("This provider does not report function-referenced strings and names."),
+                cfg: unavailable("Kuna exports no basic blocks."),
+            },
+            limitations: [
+                ...kunaLimitations("analyze_function"),
+                ...pseudocode.value.limitations,
+                KUNA_RELATIONSHIP_LIMITATION,
+                ...(relationships.ok
+                    ? []
+                    : [relationships.error.userMessage ?? relationships.error.message]),
+            ],
+        });
+        return ok({
+            result: dossier,
+            source: { kind: "project-export", project: reader.project },
+            files: [
+                ...(pseudocode.value.files ?? []),
+                ...(assembly.value.files ?? []),
+            ],
+            locations: [{ kind: "address", address: entry.address }],
+            limitations: [
+                ...pseudocode.value.limitations,
+                KUNA_RELATIONSHIP_LIMITATION,
+                ...(relationships.ok
+                    ? []
+                    : [relationships.error.userMessage ?? relationships.error.message]),
+            ],
+            referenceSource: relationships.ok
+                ? relationships.value.source
+                : {
+                    available: false,
+                    reason: relationships.error.userMessage ?? relationships.error.message,
+                },
+            relationshipCoverage: relationships.ok
+                ? combineFunctionRelationshipCoverage(relationships.value.callersCoverage, relationships.value.calleesCoverage)
+                : {
+                    status: "unknown",
+                    reason: relationships.error.userMessage ?? relationships.error.message,
+                    limited_directions: ["callers", "callees"],
+                },
+        });
+    }
+    /** Address and name lookups over one inventory, built once. */
+    #index(inventory) {
+        if (this.#inventoryIndex?.inventory === inventory)
+            return this.#inventoryIndex;
+        const byAddress = new Map();
+        const byName = new Map();
+        for (const entry of inventory) {
+            byAddress.set(entry.address, entry);
+            for (const name of new Set([entry.name, ...entry.aliases])) {
+                const named = byName.get(name);
+                if (named === undefined)
+                    byName.set(name, [entry]);
+                else
+                    named.push(entry);
+            }
+        }
+        this.#inventoryIndex = { inventory, byAddress, byName };
+        return this.#inventoryIndex;
+    }
+    /** One installation producer; only the final departing caller stops it. */
+    async #ensureInstallation(operation, signal) {
+        let attempt = this.#installation;
+        if (attempt === undefined) {
+            attempt = new SharedStartupAttempt((ownerSignal) => this.#own(this.#inspectInstallation(ownerSignal)), this.#session.signal);
+            const owned = attempt;
+            this.#installation = owned;
+            void owned.promise.then((result) => {
+                // A proven cancellation has no reusable installation result. Its
+                // complete cleanup precedes replacement; physical failures stay cached.
+                if (this.#installation === owned &&
+                    owned.signal.aborted &&
+                    (result.ok ||
+                        (result.error instanceof AnalysisCancelledError &&
+                            !result.error.cleanupIncomplete)))
+                    this.#installation = undefined;
+            });
+        }
+        const waited = await attempt.wait(signal);
+        if (waited.status === "cancelled")
+            return err(new AnalysisCancelledError(operation, { cause: signal?.reason }));
+        if (!waited.value.ok) {
+            // A fresh caller can arrive while the previous final waiter joins stop.
+            // Retry only proven cancellation, never an authored physical failure.
+            if (!signal?.aborted &&
+                attempt.signal.aborted &&
+                waited.value.error instanceof AnalysisCancelledError &&
+                !waited.value.error.cleanupIncomplete)
+                return this.#ensureInstallation(operation, signal);
+            return err(kunaQueryFailureForCaller(waited.value.error, operation));
+        }
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
+        return waited.value;
+    }
+    async #inspectInstallation(signal) {
+        const parentFileCloseResources = {
+            retain: (owner, resource) => this.#fileCloseResources.retain({
+                kind: "lease",
+                resource,
+                lease: AnalysisCleanupLease.forCloseOwner(owner, resource),
+            }),
+            run: (operation) => this.#fileCloseResources.run(operation),
+        };
+        const fileCloseScope = createKunaFileCloseScope(parentFileCloseResources);
+        try {
+            const inspected = await inspectKunaInstallation(this.#environment, {
+                fileCloseResources: fileCloseScope.owner,
+                signal,
+            });
+            if (!inspected.ok)
+                return err(kunaUnavailable("health", inspected.error.reason));
+            const committed = this.#profile?.parameters["kuna_sha256"];
+            if (committed !== undefined && committed !== inspected.value.sha256)
+                return err(new ProviderAdapterError(KUNA_PROVIDER_ID, "health", {
+                    userMessage: "The Kuna executable changed after this target was opened; reopen the target to analyze it with the current executable.",
+                    diagnostics: {
+                        committed_sha256: committed,
+                        observed_sha256: inspected.value.sha256,
+                    },
+                }));
+            return ok(inspected.value);
+        }
+        catch (cause) {
+            const cancellation = regularFileCancellation(cause);
+            if (!(cause instanceof RegularFileCleanupFailure) &&
+                cancellation !== undefined)
+                return err(new AnalysisCancelledError("health", {
+                    cause: cancellation.reason,
+                }));
+            if (!(cause instanceof RegularFileCleanupFailure))
+                return err(failure("health", cause));
+            const error = kunaFileCleanupError(cause, "health");
+            fileCloseScope.bindFailure(cause, error);
+            return err(error);
+        }
+    }
+    /** Reuse a verified export, or start building one in the background. */
+    #startProject(installation) {
+        if (this.#project !== undefined)
+            return Promise.resolve();
+        // Concurrent first requests share one lookup, which verifies every
+        // export file's digest on a fresh server.
+        this.#starting ??= this.#lookupOrBuild(installation).finally(() => {
+            this.#starting = undefined;
+        });
+        return this.#starting;
+    }
+    async #lookupOrBuild(installation) {
+        const key = kunaProjectKey({
+            targetSha256: this.#target.sha256,
+            kunaSha256: installation.sha256,
+            kunaVersion: installation.version,
+            jobs: installation.configuration.jobs,
+        });
+        this.#key = key;
+        const cached = await this.#cache.lookup(key, this.#session.signal);
+        if (cached !== undefined) {
+            this.#adopt(cached);
+            this.#project = Promise.resolve(ok(cached));
+            return;
+        }
+        let listed;
+        this.#exportInventory = new Promise((resolve) => {
+            listed = resolve;
+        });
+        this.#project = this.#cache
+            .build({
+            installation,
+            targetPath: this.#target.path,
+            targetSha256: this.#target.sha256,
+            signal: this.#session.signal,
+            onStatus: (status) => {
+                this.#status = status;
+                if (status.inventory !== null)
+                    listed(status.inventory);
+            },
+        })
+            .then((result) => {
+            listed(result.ok ? result.value.inventory : undefined);
+            if (result.ok && !this.#closing)
+                this.#adopt(result.value);
+            else if (!result.ok && !this.#closing)
+                this.#exportFailure =
+                    result.error.userMessage ?? result.error.message;
+            return result;
+        });
+    }
+    /** Retry the complete read when its immutable project disappears, never just one facet. */
+    async #withProject(operation, installation, options, read) {
+        for (let attempt = 0;; attempt += 1) {
+            const reader = await this.#awaitProject(operation, options);
+            if (!reader.ok)
+                return reader;
+            try {
+                return await read(reader.value);
+            }
+            catch (cause) {
+                if (!isMissing(cause) || attempt !== 0)
+                    throw cause;
+                this.#invalidateProject(reader.value);
+                await this.#startProject(installation);
+            }
+        }
+    }
+    #invalidateProject(reader) {
+        // Another request may already have replaced this reader and its build.
+        if (this.#reader !== reader)
+            return;
+        this.#releasePin?.();
+        this.#releasePin = undefined;
+        this.#reader = undefined;
+        this.#project = undefined;
+        this.#status = undefined;
+        this.#exportFailure = undefined;
+    }
+    #adopt(project) {
+        this.#reader = this.#readerFor(project);
+        this.#dropSingleFunctionTexts();
+        this.#releasePin ??= this.#cache.pin(project.key);
+    }
+    #readerFor(project) {
+        return this.#reader?.project === project
+            ? this.#reader
+            : new KunaProjectReader(project, {
+                signal: this.#session.signal,
+                own: (work) => this.#own(work),
+            });
+    }
+    /** The export's failure once it has settled; undefined while it builds or after success. */
+    async #settledExportFailure() {
+        const settled = await Promise.race([
+            this.#project,
+            Promise.resolve(undefined),
+        ]);
+        if (settled === undefined || settled.ok)
+            return undefined;
+        return settled.error.userMessage ?? settled.error.message;
+    }
+    /** Wait for the export, reporting progress, without cancelling it for other callers. */
+    async #awaitProject(operation, options) {
+        if (this.#reader !== undefined)
+            return ok(this.#reader);
+        const project = this.#project;
+        if (project === undefined)
+            return err(new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {
+                userMessage: "The Kuna project export was never started.",
+            }));
+        const started = Date.now();
+        const progress = options.progress;
+        // Report waiting only; Kuna exposes no measure of completed export work.
+        const timer = setInterval(() => {
+            void progress
+                ?.report({
+                phase: "kuna_export",
+                completed: 0,
+                total: null,
+                message: `Waiting for Kuna's project export (${this.#status?.phase ?? "starting"}, ${String(Math.floor((Date.now() - started) / 1000))}s elapsed); it serves this request and every later one`,
+            })
+                .catch(() => undefined);
+        }, WAIT_PROGRESS_INTERVAL_MS);
+        try {
+            const built = await waitFor(project, options.signal, operation);
+            if (!built.ok)
+                return err(exportUnavailable(operation, built.error));
+            return ok(this.#readerFor(built.value));
+        }
+        finally {
+            clearInterval(timer);
+        }
+    }
+    /** The published or building export's inventory, otherwise one `kuna functions` run. */
+    async #ensureInventory(installation, options) {
+        if (this.#reader !== undefined)
+            return ok(this.#reader.project.inventory);
+        const exported = this.#status?.inventory;
+        if (exported !== undefined && exported !== null)
+            return ok(exported);
+        if (this.#inventory === undefined) {
+            // The session owns the shared run; each caller only stops waiting.
+            const run = this.#listInventory(installation);
+            this.#inventory = run;
+            void run.then((listed) => {
+                // A failed listing is retried by the next request.
+                if (!listed.ok && this.#inventory === run)
+                    this.#inventory = undefined;
+            });
+        }
+        return waitFor(this.#inventory, options.signal, "list_procedures");
+    }
+    /**
+     * The export lists every callable entry before it decompiles, so listings
+     * wait for that inventory. Only an export that ends without one, or none at
+     * all, leads to a separate `kuna functions` run.
+     */
+    async #listInventory(installation) {
+        // A concurrent text request may still be choosing between the cache and a
+        // build; its outcome decides whether an inventory already exists.
+        await this.#starting?.catch(() => undefined);
+        if (this.#reader !== undefined)
+            return ok(this.#reader.project.inventory);
+        const exported = await this.#exportInventory;
+        if (exported !== undefined)
+            return ok(exported);
+        const run = await this.#commands.run({
+            installation,
+            arguments: (input) => ["functions", input, "--json"],
+            operation: "list_procedures",
+            deadline: kunaFunctionDeadline(installation.configuration),
+            outputBytes: KUNA_INVENTORY_OUTPUT_BYTES,
+            signal: this.#session.signal,
+        });
+        if (!run.ok)
+            return run;
+        const inventory = parseKunaInventory(run.value.stdout.text);
+        return inventory.ok
+            ? ok(inventory.value)
+            : err(new ProviderAdapterError(KUNA_PROVIDER_ID, "list_procedures", {
+                userMessage: `Kuna's function inventory is not usable: ${inventory.error}`,
+            }));
+    }
+}