Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(kuna): add Kuna readiness, doctor and owned project cache (#3832)
Kaoru0822933f216698fc
diff --git a/src/application/DoctorProviderIds.ts b/src/application/DoctorProviderIds.tsindex af31f4c68..06a4f13a6 100644--- a/src/application/DoctorProviderIds.ts+++ b/src/application/DoctorProviderIds.ts@@ -1,2 +1,8 @@/** Deep-analysis providers whose readiness can be selected explicitly by doctor. */-export const DOCTOR_PROVIDER_IDS = ["hopper", "ghidra", "ida", "jadx"] as const;+export const DOCTOR_PROVIDER_IDS = [+ "hopper",+ "ghidra",+ "ida",+ "jadx",+ "kuna",+] as const;diff --git a/src/doctorRuntime.test.ts b/src/doctorRuntime.test.tsindex c62bd0f5c..265c96c5e 100644--- a/src/doctorRuntime.test.ts+++ b/src/doctorRuntime.test.ts@@ -42,6 +42,27 @@ it("omits REA_JADX_MCP_JAR from the provider registration environment when it isexpect(environment).not.toHaveProperty("REA_JADX_MCP_JAR");});+it("carries a validated REA_KUNA_COMMAND into the provider registration environment", async () => {+ expect(DOCTOR_PROVIDER_IDS).toContain("kuna");+ const root = await createTestTempDirectory("rea-kuna-registration-");+ const kuna = join(root, "kuna");+ await writeFile(kuna, "#!/bin/sh\nprintf 'kuna 1.833\\n'\n", { mode: 0o700 });++ const inspections = await createSystemDoctorHost({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: join(root, "cache"),+ }).providerInspections?.();++ expect(inspections?.find(({ id }) => id === "kuna")).toMatchObject({+ available: true,+ providerVersion: "1.833",+ });+ expect(providerRegistrationEnvironment(inspections ?? [])).toMatchObject({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: join(root, "cache"),+ });+});+const createFakeJdk = async (root: string): Promise<string> => {const javaHome = join(root, "fake-jdk");const bin = join(javaHome, "bin");diff --git a/src/doctorRuntime.ts b/src/doctorRuntime.tsindex b6ab62d63..e85238db4 100644--- a/src/doctorRuntime.ts+++ b/src/doctorRuntime.ts@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";import { inspectJadxProvider } from "./android/JadxDoctor.js";import { inspectSystemGhidraProvider } from "./ghidra/GhidraDoctor.js";import { inspectIdaRegistration } from "./ida/IdaDoctor.js";+import { inspectKunaProvider } from "./kuna/KunaDoctor.js";import { readIdaConfiguration } from "./ida/IdaConfiguration.js";import { parseJebMcpEndpoint } from "./jeb/JebMcpEndpoint.js";import { selectLinuxPrivateDisplayStrategy } from "./hopper/LinuxPrivateDisplayProbe.js";@@ -45,6 +46,7 @@ export const createSystemDoctorHost = (await inspectSystemGhidraProvider(environment),inspectIdaRegistration(environment.REA_IDA_MCP_CONFIG),await inspectJadxProvider(environment),+ await inspectKunaProvider(environment),],linuxDemoRuntimeCheck: () => inspectLinuxPrivateDisplay(environment),});diff --git a/src/kuna/KunaConfiguration.ts b/src/kuna/KunaConfiguration.tsnew file mode 100644index 000000000..48fe41864--- /dev/null+++ b/src/kuna/KunaConfiguration.ts@@ -0,0 +1,144 @@+import { isAbsolute, join } from "node:path";++import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";+import { providerStartupTimeoutSchema } from "../config/providerStartupTimeout.js";+import { err, ok, type Result } from "../domain/result.js";+import {+ KUNA_COMMAND_REMEDIATION,+ KUNA_UNSUPPORTED_HOST_REMEDIATION,+} from "./KunaRelease.js";++/** Kuna caps its own decode lanes and worker pool at 32. */+const MAX_KUNA_JOBS = 32;++/**+ * A 1.4 MB sqlite3 shell exported serially in 66-108 s on Apple M-series and+ * Linux hosts; thirty minutes admits images an order of magnitude larger+ * without an unbounded run. Larger images need a raised deadline or more jobs.+ */+const DEFAULT_PROJECT_TIMEOUT_MS = 30 * 60 * 1000;++/**+ * A serial (`--jobs 1`) export is Kuna's reference answer: it decompiles+ * callees before callers, which recovers prototypes that parallel workers+ * cannot. Measured on coreutils sort, 40-60% of functions differ otherwise.+ */+const DEFAULT_JOBS = 1;++/** Measured sqlite3 exports occupy ~25 MiB; four GiB retains many projects. */+const DEFAULT_CACHE_MAX_BYTES = 4 * 1024 ** 3;++/** One project needs its .c, .h, .asm, inventory and manifest; refuse smaller caps. */+const MIN_CACHE_MAX_BYTES = 1024 ** 2;++/** Caller-selected Kuna installation and REA-owned project cache policy. */+export interface KunaConfiguration {+ /** Caller-selected executable path, preserved exactly as configured. */+ readonly command: string;+ /** REA-owned cache root; Kuna's own spec cache lives beneath it too. */+ readonly cacheRoot: string;+ readonly cacheMaxBytes: number;+ readonly projectTimeoutMs: number;+ readonly jobs: number;+}++/** Why the configured environment cannot select a Kuna installation. */+export interface KunaConfigurationFailure {+ readonly code: "not_configured" | "open_options_invalid" | "unsupported_host";+ readonly reason: string;+ readonly setting: string | null;+}++const failure = (+ code: KunaConfigurationFailure["code"],+ reason: string,+ setting: string | null = null,+): Result<never, KunaConfigurationFailure> => err({ code, reason, setting });++const positiveInteger = (value: string): number | undefined =>+ /^[1-9]\d*$/u.test(value) && Number.isSafeInteger(Number(value))+ ? Number(value)+ : undefined;++/** Per-user cache directory that REA owns for Kuna on this host. */+const defaultCacheRoot = (+ environment: Readonly<NodeJS.ProcessEnv>,+ platform: NodeJS.Platform,+): string => {+ const home = homeDirectoryFromEnvironment(environment, platform);+ if (platform === "darwin")+ return join(home, "Library", "Caches", "rea", "kuna");+ const xdg = environment.XDG_CACHE_HOME;+ return join(+ xdg !== undefined && isAbsolute(xdg) ? xdg : join(home, ".cache"),+ "rea",+ "kuna",+ );+};++/** Parse the Kuna settings without touching the filesystem or the executable. */+export const readKunaConfiguration = (+ environment: Readonly<NodeJS.ProcessEnv>,+ platform: NodeJS.Platform = process.platform,+): Result<KunaConfiguration, KunaConfigurationFailure> => {+ const command = environment.REA_KUNA_COMMAND;+ if (command === undefined || command.length === 0)+ return failure("not_configured", KUNA_COMMAND_REMEDIATION);+ if (!isAbsolute(command))+ return failure(+ "open_options_invalid",+ `REA_KUNA_COMMAND must be an absolute path; received ${command}. ${KUNA_COMMAND_REMEDIATION}`,+ "REA_KUNA_COMMAND",+ );+ if (platform !== "darwin" && platform !== "linux")+ return failure("unsupported_host", KUNA_UNSUPPORTED_HOST_REMEDIATION);++ const cacheRoot = environment.REA_KUNA_CACHE_DIR;+ if (cacheRoot !== undefined && !isAbsolute(cacheRoot))+ return failure(+ "open_options_invalid",+ `REA_KUNA_CACHE_DIR must be an absolute directory; received ${cacheRoot}.`,+ "REA_KUNA_CACHE_DIR",+ );++ const rawMaxBytes = environment.REA_KUNA_CACHE_MAX_BYTES;+ const cacheMaxBytes =+ rawMaxBytes === undefined+ ? DEFAULT_CACHE_MAX_BYTES+ : positiveInteger(rawMaxBytes);+ if (cacheMaxBytes === undefined || cacheMaxBytes < MIN_CACHE_MAX_BYTES)+ return failure(+ "open_options_invalid",+ `REA_KUNA_CACHE_MAX_BYTES must be a decimal byte count of at least ${String(MIN_CACHE_MAX_BYTES)}; received ${String(rawMaxBytes)}.`,+ "REA_KUNA_CACHE_MAX_BYTES",+ );++ const rawTimeout = environment.REA_KUNA_PROJECT_TIMEOUT_MS;+ const timeout =+ rawTimeout === undefined+ ? undefined+ : providerStartupTimeoutSchema.safeParse(rawTimeout);+ if (timeout !== undefined && !timeout.success)+ return failure(+ "open_options_invalid",+ `REA_KUNA_PROJECT_TIMEOUT_MS must be a decimal millisecond count from 1 to 2147483647; received ${String(rawTimeout)}.`,+ "REA_KUNA_PROJECT_TIMEOUT_MS",+ );++ const rawJobs = environment.REA_KUNA_JOBS;+ const jobs = rawJobs === undefined ? DEFAULT_JOBS : positiveInteger(rawJobs);+ if (jobs === undefined || jobs > MAX_KUNA_JOBS)+ return failure(+ "open_options_invalid",+ `REA_KUNA_JOBS must be an integer from 1 to ${String(MAX_KUNA_JOBS)}; received ${String(rawJobs)}.`,+ "REA_KUNA_JOBS",+ );++ return ok({+ command,+ cacheRoot: cacheRoot ?? defaultCacheRoot(environment, platform),+ cacheMaxBytes,+ projectTimeoutMs: timeout?.data ?? DEFAULT_PROJECT_TIMEOUT_MS,+ jobs,+ });+};diff --git a/src/kuna/KunaDoctor.ts b/src/kuna/KunaDoctor.tsnew file mode 100644index 000000000..4c3488dfb--- /dev/null+++ b/src/kuna/KunaDoctor.ts@@ -0,0 +1,211 @@+import { constants } from "node:fs";+import { access, stat } from "node:fs/promises";+import { dirname } from "node:path";++import type {+ DoctorProviderCheck,+ DoctorProviderInspection,+} from "../application/Doctor.js";+import { readKunaConfiguration } from "./KunaConfiguration.js";+import {+ inspectKunaInstallation,+ type KunaReadinessFailure,+} from "./KunaInstallation.js";+import {+ KUNA_COMMAND_REMEDIATION,+ KUNA_PROVIDER_ID,+ KUNA_UNSUPPORTED_HOST_REMEDIATION,+ KUNA_VERIFIED_VERSION,+ KUNA_VERSION_PROBE_REMEDIATION,+} from "./KunaRelease.js";++/** Settings a registration may carry; only those the caller set explicitly. */+const REGISTRATION_SETTINGS = [+ "REA_KUNA_COMMAND",+ "REA_KUNA_CACHE_DIR",+ "REA_KUNA_CACHE_MAX_BYTES",+ "REA_KUNA_PROJECT_TIMEOUT_MS",+ "REA_KUNA_JOBS",+] as const;++/** Project Kuna readiness into the doctor contract without writing anything. */+export const inspectKunaProvider = async (+ environment: Readonly<NodeJS.ProcessEnv>,+ platform: NodeJS.Platform = process.platform,+): Promise<DoctorProviderInspection> => {+ const installation = await inspectKunaInstallation(environment, {+ platform,+ });+ const configured =+ environment.REA_KUNA_COMMAND !== undefined &&+ environment.REA_KUNA_COMMAND.length > 0;+ if (!installation.ok)+ return {+ id: KUNA_PROVIDER_ID,+ configured,+ available: false,+ providerVersion: null,+ registrationEnvironment: {},+ checks: [installationFailure(installation.error, configured)],+ };+ const { value } = installation;+ return {+ id: KUNA_PROVIDER_ID,+ configured,+ available: true,+ providerVersion: value.version,+ registrationEnvironment: Object.fromEntries(+ REGISTRATION_SETTINGS.flatMap((name) => {+ const setting = environment[name];+ return setting === undefined ? [] : [[name, setting]];+ }),+ ),+ checks: [+ {+ name: "installation",+ ok: true,+ code: null,+ detail: `${value.executable} reports Kuna ${value.version} (sha256 ${value.sha256})${+ value.verified+ ? "."+ : `; REA verified ${KUNA_VERIFIED_VERSION}, so this release's project layout is unverified.`+ }`,+ remediation: null,+ classification: "config_drift",+ details: {+ executable: value.executable,+ version: value.version,+ verified_version: KUNA_VERIFIED_VERSION,+ sha256: value.sha256,+ },+ },+ await cacheCheck(environment, platform),+ ],+ };+};++const installationFailure = (+ failure: KunaReadinessFailure,+ configured: boolean,+): DoctorProviderCheck => ({+ name: "installation",+ ok: false,+ code: failure.code,+ detail: failure.reason,+ remediation:+ failure.code === "unsupported_host"+ ? KUNA_UNSUPPORTED_HOST_REMEDIATION+ : failure.code === "version_unresolved"+ ? KUNA_VERSION_PROBE_REMEDIATION+ : KUNA_COMMAND_REMEDIATION,+ classification:+ failure.code === "unsupported_host"+ ? "unsupported_host"+ : configured+ ? "config_drift"+ : "missing_analysis_engine",+ details: failure.diagnostics,+});++/** The cache root may not exist yet; doctor reports it without creating it. */+const cacheCheck = async (+ environment: Readonly<NodeJS.ProcessEnv>,+ platform: NodeJS.Platform,+): Promise<DoctorProviderCheck> => {+ const configuration = readKunaConfiguration(environment, platform);+ if (!configuration.ok)+ return {+ name: "cache",+ ok: false,+ code: configuration.error.code,+ detail: configuration.error.reason,+ remediation: KUNA_COMMAND_REMEDIATION,+ classification: "config_drift",+ };+ const { cacheRoot, cacheMaxBytes } = configuration.value;+ const details = { cache_root: cacheRoot, cache_max_bytes: cacheMaxBytes };+ try {+ if (!(await stat(cacheRoot)).isDirectory())+ return {+ name: "cache",+ ok: false,+ code: "open_options_invalid",+ detail: `The Kuna cache root ${cacheRoot} exists but is not a directory.`,+ remediation:+ "Set REA_KUNA_CACHE_DIR to a directory REA may own, or remove the conflicting file.",+ classification: "config_drift",+ details,+ };+ await access(cacheRoot, constants.W_OK | constants.X_OK);+ } catch (cause: unknown) {+ if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") {+ const creatable = await nearestDirectoryWritable(cacheRoot);+ return creatable.ok+ ? {+ name: "cache",+ ok: true,+ code: null,+ detail: `REA creates the Kuna project cache at ${cacheRoot} on first use.`,+ remediation: null,+ classification: "config_drift",+ details,+ }+ : {+ name: "cache",+ ok: false,+ code: "open_options_invalid",+ detail: `REA cannot create the Kuna cache root ${cacheRoot}: ${creatable.reason}`,+ remediation:+ "Set REA_KUNA_CACHE_DIR to a directory the REA process user can create or write.",+ classification: "config_drift",+ details,+ };+ }+ return {+ name: "cache",+ ok: false,+ code: "open_options_invalid",+ detail: `REA cannot write the Kuna cache root ${cacheRoot}: ${cause instanceof Error ? cause.message : String(cause)}`,+ remediation:+ "Set REA_KUNA_CACHE_DIR to a directory the REA process user can write.",+ classification: "config_drift",+ details,+ };+ }+ return {+ name: "cache",+ ok: true,+ code: null,+ detail: `Kuna project exports are cached in ${cacheRoot} (at most ${String(cacheMaxBytes)} bytes).`,+ remediation: null,+ classification: "config_drift",+ details,+ };+};++/** Whether the nearest existing ancestor is a directory REA may create entries in. */+const nearestDirectoryWritable = async (+ path: string,+): Promise<+ { readonly ok: true } | { readonly ok: false; readonly reason: string }+> => {+ let candidate = dirname(path);+ for (;;) {+ try {+ if (!(await stat(candidate)).isDirectory())+ return { ok: false, reason: `${candidate} is not a directory.` };+ await access(candidate, constants.W_OK | constants.X_OK);+ return { ok: true };+ } catch (cause: unknown) {+ const missing =+ cause instanceof Error && "code" in cause && cause.code === "ENOENT";+ const parent = dirname(candidate);+ if (!missing || parent === candidate)+ return {+ ok: false,+ reason: `${candidate} is not writable: ${cause instanceof Error ? cause.message : String(cause)}`,+ };+ candidate = parent;+ }+ }+};diff --git a/src/kuna/KunaInstallation.ts b/src/kuna/KunaInstallation.tsnew file mode 100644index 000000000..5ba0c58b1--- /dev/null+++ b/src/kuna/KunaInstallation.ts@@ -0,0 +1,191 @@+import { constants } from "node:fs";+import { access, open, realpath, stat } from "node:fs/promises";+import { join } from "node:path";++import type { JsonValue } from "../domain/jsonValue.js";+import { err, ok, type Result } from "../domain/result.js";+import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ execFileOutput,+ execFileOutputFailure,+} from "../process/ExecFileOutput.js";+import {+ readKunaConfiguration,+ type KunaConfiguration,+ type KunaConfigurationFailure,+} from "./KunaConfiguration.js";+import {+ KUNA_COMMAND_REMEDIATION,+ KUNA_VERIFIED_VERSION,+ KUNA_VERSION_PROBE_REMEDIATION,+} from "./KunaRelease.js";++/** `kuna --version` exits before loading specs or an input; it needs no budget beyond this. */+const VERSION_PROBE_TIMEOUT_MS = 10_000;+const VERSION_PROBE_MAX_OUTPUT_BYTES = 64 * 1024;++/** Release CI prints exactly `kuna <MAJOR.MINOR>`; source builds print the Cargo version. */+const VERSION_LINE = /^kuna (\d+\.\d+(?:\.\d+)?)\r?\n?$/u;++/** One observed Kuna executable, identified by its bytes as well as its version. */+export interface KunaInstallation {+ readonly configuration: KunaConfiguration;+ /** Canonical path of the probed executable. */+ readonly executable: string;+ readonly version: string;+ /** Whether this release is the one REA verified. */+ readonly verified: boolean;+ readonly sha256: string;+ readonly bytes: number;+ /**+ * Whether the executable is a `#!` script, such as a package-manager shim.+ * Its process then reports the interpreter as its command, so ownership+ * checks cannot match the configured path by argv prefix.+ */+ readonly script: boolean;+}++/** Why the selected Kuna installation cannot be used. */+export interface KunaReadinessFailure {+ readonly code:+ | KunaConfigurationFailure["code"]+ | "executable_missing"+ | "version_unresolved";+ readonly reason: string;+ readonly diagnostics: Readonly<Record<string, JsonValue>>;+}++/**+ * Environment for every Kuna child. Kuna unpacks its built-in SLEIGH tree into+ * the per-user cache under HOME (macOS) or XDG_CACHE_HOME (Linux), so both+ * point inside REA's own cache root instead of the user's.+ */+export const kunaChildEnvironment = (+ configuration: KunaConfiguration,+): NodeJS.ProcessEnv => {+ const home = join(configuration.cacheRoot, "home");+ return {+ HOME: home,+ XDG_CACHE_HOME: join(home, ".cache"),+ NO_COLOR: "1",+ };+};++const failure = (+ code: KunaReadinessFailure["code"],+ reason: string,+ diagnostics: Readonly<Record<string, JsonValue>>,+): Result<never, KunaReadinessFailure> => err({ code, reason, diagnostics });++const message = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);++/** Resolve, version-probe and fingerprint the configured executable. */+export const inspectKunaInstallation = async (+ environment: Readonly<NodeJS.ProcessEnv>,+ options: {+ readonly platform?: NodeJS.Platform;+ readonly signal?: AbortSignal;+ /** Probe deadline; tests shorten it. */+ readonly probeTimeoutMs?: number;+ } = {},+): Promise<Result<KunaInstallation, KunaReadinessFailure>> => {+ const configuration = readKunaConfiguration(environment, options.platform);+ if (!configuration.ok)+ return failure(configuration.error.code, configuration.error.reason, {+ configured: configuration.error.code !== "not_configured",+ ...(configuration.error.setting === null+ ? {}+ : { setting: configuration.error.setting }),+ });+ const { command } = configuration.value;++ let executable: string;+ try {+ executable = await realpath(command);+ await access(executable, constants.X_OK);+ if (!(await stat(executable)).isFile())+ return failure(+ "executable_missing",+ `REA_KUNA_COMMAND is not a regular file: ${command}. ${KUNA_COMMAND_REMEDIATION}`,+ { command },+ );+ } catch (cause: unknown) {+ options.signal?.throwIfAborted();+ return failure(+ "executable_missing",+ `Cannot execute REA_KUNA_COMMAND ${command}: ${message(cause)}. ${KUNA_COMMAND_REMEDIATION}`,+ { command },+ );+ }++ const deadline = options.probeTimeoutMs ?? VERSION_PROBE_TIMEOUT_MS;+ let stdout: string;+ try {+ ({ stdout } = await execFileOutput(executable, ["--version"], {+ env: kunaChildEnvironment(configuration.value),+ timeout: deadline,+ maxBuffer: VERSION_PROBE_MAX_OUTPUT_BYTES,+ // Escalate to SIGKILL so an executable that ignores SIGTERM cannot hang doctor.+ stopSignal: "SIGTERM",+ ...(options.signal === undefined ? {} : { signal: options.signal }),+ }));+ } catch (cause: unknown) {+ options.signal?.throwIfAborted();+ const output = execFileOutputFailure(cause);+ return failure(+ "version_unresolved",+ `${executable} --version failed: ${output?.stderr.trim() || message(cause)}. ${KUNA_VERSION_PROBE_REMEDIATION}`,+ {+ command,+ executable,+ exit_code: typeof output?.code === "number" ? output.code : null,+ signal: output?.signal ?? null,+ killed: output?.killed ?? false,+ output_truncated: output?.outputTruncated ?? false,+ deadline_ms: deadline,+ },+ );+ }+ const version = VERSION_LINE.exec(stdout)?.[1];+ if (version === undefined)+ return failure(+ "version_unresolved",+ `${executable} --version printed no recognizable Kuna version. ${KUNA_VERSION_PROBE_REMEDIATION}`,+ { command, executable, stdout: stdout.slice(0, 256) },+ );++ let fingerprint: { readonly sha256: string; readonly bytes: number };+ let script: boolean;+ try {+ fingerprint = await hashStableFile(executable, options.signal);+ script = await startsWithShebang(executable);+ } catch (cause: unknown) {+ options.signal?.throwIfAborted();+ return failure(+ "executable_missing",+ `Cannot fingerprint ${executable}: ${message(cause)}`,+ { command, executable },+ );+ }++ return ok({+ configuration: configuration.value,+ executable,+ version,+ verified: version === KUNA_VERIFIED_VERSION,+ ...fingerprint,+ script,+ });+};++const startsWithShebang = async (path: string): Promise<boolean> => {+ const handle = await open(path, "r");+ try {+ const prefix = Buffer.alloc(2);+ const { bytesRead } = await handle.read(prefix, 0, 2, 0);+ return bytesRead === 2 && prefix.toString("latin1") === "#!";+ } finally {+ await handle.close();+ }+};diff --git a/src/kuna/KunaProjectCache.ts b/src/kuna/KunaProjectCache.tsnew file mode 100644index 000000000..9bdcb406f--- /dev/null+++ b/src/kuna/KunaProjectCache.ts@@ -0,0 +1,690 @@+import { createHash, randomUUID } from "node:crypto";+import {+ mkdir,+ mkdtemp,+ readdir,+ readFile,+ rename,+ rm,+ stat,+ utimes,+} from "node:fs/promises";+import { join } from "node:path";++import canonicalize from "canonicalize";+import writeFileAtomic from "write-file-atomic";+import { z } from "zod";++import type { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisResourceConstraintError,+} from "../domain/analysisErrorCore.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { err, ok, type Result } from "../domain/result.js";+import { hashStableFile } from "../filesystem/StableFileHash.js";+import type { KunaInstallation } from "./KunaInstallation.js";+import {+ exportKunaProject,+ KUNA_EXPORT_OPERATION,+ kunaExportFailure,+ readKunaExport,+ type KunaExport,+ type KunaExportStatus,+ type KunaProcessLauncher,+} from "./KunaProjectExport.js";+import type {+ KunaInventoryFunction,+ KunaProjectFunction,+} from "./KunaProjectFiles.js";+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";++/** Bumped whenever the entry layout or manifest meaning changes. */+const CACHE_LAYOUT = 1;++/** A manifest names five files and their digests; anything larger is not ours. */+const MANIFEST_MAX_BYTES = 64 * 1024;++const KEY_PATTERN = /^[0-9a-f]{64}$/u;++const SHA256_PATTERN = /^[0-9a-f]{64}$/u;++/** Inputs that determine an export's content. Each one is part of the cache key. */+export interface KunaProjectKeyInputs {+ readonly targetSha256: string;+ readonly kunaSha256: string;+ readonly kunaVersion: string;+ /**+ * `--jobs 1` is Kuna's reference answer; more jobs decompile without+ * callee-first prototypes and change some bodies.+ */+ readonly jobs: number;+}++/** Content address of one export: every input that can change its bytes. */+export const kunaProjectKey = (inputs: KunaProjectKeyInputs): string =>+ createHash("sha256")+ .update(+ canonicalize({+ layout: CACHE_LAYOUT,+ target_sha256: inputs.targetSha256,+ kuna_sha256: inputs.kunaSha256,+ kuna_version: inputs.kunaVersion,+ export: { command: "decompile-project", jobs: inputs.jobs },+ }) ?? "",+ )+ .digest("hex");++const fileSchema = z.strictObject({+ path: z.string().min(1),+ bytes: z.number().int().nonnegative(),+ sha256: z.string().regex(SHA256_PATTERN),+});++const manifestSchema = z.strictObject({+ layout: z.literal(CACHE_LAYOUT),+ key: z.string().regex(KEY_PATTERN),+ inputs: z.strictObject({+ target_sha256: z.string().regex(SHA256_PATTERN),+ kuna_sha256: z.string().regex(SHA256_PATTERN),+ kuna_version: z.string().min(1),+ jobs: z.number().int().positive(),+ }),+ files: z.strictObject({+ c: fileSchema,+ h: fileSchema,+ asm: fileSchema,+ readme: fileSchema,+ inventory: fileSchema,+ }),+ summary: z.strictObject({+ decompiled: z.number().int().nonnegative(),+ failed: z.number().int().nonnegative(),+ }),+ created_at: z.string().datetime(),+});++/** Immutable description of one published export, written once at publish. */+export type KunaProjectManifest = z.infer<typeof manifestSchema>;++/** One verified, published export. */+export interface KunaProject {+ readonly key: string;+ /** Directory holding the export's `.c`, `.h`, `.asm`, README and inventory. */+ readonly directory: string;+ readonly manifest: KunaProjectManifest;+ /** Decompiled function blocks in `.c` order. */+ readonly functions: readonly KunaProjectFunction[];+ /** Every callable entry Kuna found, including imports it does not decompile. */+ readonly inventory: readonly KunaInventoryFunction[];+}++/** One request to produce or reuse the export for a target. */+export interface KunaProjectRequest {+ readonly installation: KunaInstallation;+ /** Caller-selected target path; REA decompiles a verified copy of it. */+ readonly targetPath: string;+ readonly targetSha256: string;+ readonly signal?: AbortSignal;+ readonly onStatus?: (status: KunaExportStatus) => void;+}++interface StagedResult {+ readonly result: Result<KunaProject, AnalysisError>;+ /** Set when an owned process may still write into staging. */+ readonly retainStaging: boolean;+}++interface InflightBuild {+ readonly key: string;+ readonly promise: Promise<Result<KunaProject, AnalysisError>>;+ readonly controller: AbortController;+ readonly listeners: Set<(status: KunaExportStatus) => void>;+ waiters: number;+}++const isMissing = (cause: unknown): boolean =>+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "ENOENT" || cause.code === "ENOTDIR");++/** A file an entry's manifest names is gone, replaced or changed under it. */+const isDamaged = (cause: unknown): boolean =>+ cause instanceof Error &&+ "code" in cause &&+ ["ENOENT", "ENOTDIR", "EISDIR", "ENOTFILE", "ESTALE"].includes(+ String(cause.code),+ );++const isPublishedByAnother = (cause: unknown): boolean =>+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "EEXIST" || cause.code === "ENOTEMPTY");++const parseManifest = (text: string): KunaProjectManifest | undefined => {+ try {+ const parsed = manifestSchema.safeParse(JSON.parse(text));+ return parsed.success ? parsed.data : undefined;+ } catch {+ return undefined;+ }+};++const manifestBytes = (manifest: KunaProjectManifest): number =>+ Object.values(manifest.files).reduce((sum, file) => sum + file.bytes, 0);++/**+ * REA-owned on-disk cache of `kuna decompile-project` exports.+ *+ * Layout under the root: `projects/<key>/` holds published entries+ * (`manifest.json` plus the export and inventory in `project/`), `staging/`+ * holds builds whose processes may still be live, `trash/` holds retired+ * workspaces and evicted entries awaiting removal,+ * and `home/` is Kuna's own HOME so its spec cache stays inside REA's+ * ownership.+ *+ * Entries are content-addressed and immutable. A build runs in private+ * staging and is published by one directory rename, so a reader sees a+ * complete entry or none, and concurrent publishers of one key keep the first.+ * File digests are recorded once at publish and checked on every first read.+ * Recency is the entry directory's mtime; publishing evicts the least recently+ * used entries above the size cap, never an entry pinned by this process.+ */+export class KunaProjectCache {+ readonly #root: string;+ readonly #maxBytes: number;+ readonly #launcher: KunaProcessLauncher | undefined;+ /** Builds new requests may join, at most one per key. */+ readonly #inflight = new Map<string, InflightBuild>();+ /** Every build not yet settled, including abandoned ones a retry replaced. */+ readonly #unfinished = new Set<InflightBuild>();+ readonly #verified = new Map<string, KunaProject>();+ readonly #pins = new Map<string, number>();+ /** One eviction decision at a time; exports themselves remain concurrent. */+ #eviction: Promise<void> = Promise.resolve();+ #capacity: "within_limit" | "pinned" | "building" = "within_limit";+ #maintenance: Promise<void> | undefined;+ #maintenanceRequested = false;+ readonly #retainedProcesses: ProviderCleanupError[] = [];+ /** Only resources whose process cleanup is proven may be retried as files. */+ readonly #retainedFiles = new Map<string, ProviderCleanupError>();++ constructor(+ root: string,+ options: {+ readonly maxBytes: number;+ readonly launcher?: KunaProcessLauncher;+ },+ ) {+ this.#root = root;+ this.#maxBytes = options.maxBytes;+ this.#launcher = options.launcher;+ }++ /** Keep an entry from eviction while this process serves it. */+ pin(key: string): () => void {+ this.#pins.set(key, (this.#pins.get(key) ?? 0) + 1);+ let released = false;+ return () => {+ if (released) return;+ released = true;+ const count = (this.#pins.get(key) ?? 1) - 1;+ if (count === 0) {+ this.#pins.delete(key);+ if (this.#capacity !== "within_limit") this.#scheduleEviction();+ } else this.#pins.set(key, count);+ };+ }++ /**+ * Return the verified published entry for a key, or undefined when none is+ * usable. A corrupt or tampered entry is removed and reported as absent.+ */+ async lookup(+ key: string,+ signal?: AbortSignal,+ ): Promise<KunaProject | undefined> {+ const verified = this.#verified.get(key);+ if (verified !== undefined) {+ // Another process may have evicted it since this one verified it.+ if (await this.#touch(key)) return verified;+ this.#verified.delete(key);+ return undefined;+ }+ const entry = join(this.#root, "projects", key);+ let text: string;+ try {+ text = await this.#readBounded(join(entry, "manifest.json"));+ } catch (cause: unknown) {+ if (isMissing(cause)) return undefined;+ if (!(cause instanceof RangeError)) throw cause;+ await this.#discard(key);+ return undefined;+ }+ const manifest = parseManifest(text);+ if (manifest?.key !== key) {+ await this.#discard(key);+ return undefined;+ }+ const directory = join(entry, "project");+ for (const file of Object.values(manifest.files)) {+ let observed: { readonly sha256: string; readonly bytes: number };+ try {+ observed = await hashStableFile(join(directory, file.path), signal);+ } catch (cause: unknown) {+ signal?.throwIfAborted();+ if (!isDamaged(cause)) throw cause;+ await this.#discard(key);+ return undefined;+ }+ if (observed.sha256 !== file.sha256 || observed.bytes !== file.bytes) {+ await this.#discard(key);+ return undefined;+ }+ }+ const parsed = await readKunaExport(+ directory,+ manifest.files,+ manifest.summary,+ signal,+ );+ if (!parsed.ok) {+ await this.#discard(key);+ return undefined;+ }+ const project = { key, directory, manifest, ...parsed.value };+ if (!(await this.#touch(key))) return undefined;+ this.#verified.set(key, project);+ return project;+ }++ /**+ * Return the entry for a request, building and publishing it when absent.+ * Concurrent requests for one key share one Kuna run; the run is cancelled+ * only when every waiting request has been cancelled.+ */+ async build(+ request: KunaProjectRequest,+ ): Promise<Result<KunaProject, AnalysisError>> {+ if (request.signal?.aborted === true)+ return err(new AnalysisCancelledError(KUNA_EXPORT_OPERATION));+ const key = kunaProjectKey({+ targetSha256: request.targetSha256,+ kunaSha256: request.installation.sha256,+ kunaVersion: request.installation.version,+ jobs: request.installation.configuration.jobs,+ });+ const running = this.#inflight.get(key);+ // A build whose waiters all left is winding down; a new request starts afresh.+ if (running !== undefined && !running.controller.signal.aborted)+ return this.#await(running, request);+ const controller = new AbortController();+ const listeners = new Set<(status: KunaExportStatus) => void>();+ const promise = this.#produce(key, request, controller.signal, (status) => {+ for (const listener of listeners) listener(status);+ });+ const created: InflightBuild = {+ key,+ promise,+ controller,+ listeners,+ waiters: 0,+ };+ this.#inflight.set(key, created);+ this.#unfinished.add(created);+ void promise.then(() => {+ this.#unfinished.delete(created);+ if (this.#inflight.get(key) === created) this.#inflight.delete(key);+ if (this.#unfinished.size === 0 && this.#capacity === "building")+ this.#scheduleEviction();+ });+ return this.#await(created, request);+ }++ /** Wait for builds, retry safe file removal, and report unresolved cleanup. */+ async close(): Promise<Result<null, ProviderCleanupError>> {+ await Promise.allSettled(+ [...this.#unfinished].map((entry) => entry.promise),+ );+ while (this.#maintenance !== undefined) await this.#maintenance;+ for (const path of [...this.#retainedFiles.keys()])+ await this.#removeRetired(path).catch(() => undefined);+ const retained = [+ ...this.#retainedProcesses,+ ...this.#retainedFiles.values(),+ ];+ if (retained.length === 0) return ok(null);+ return err(+ new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ retained.flatMap((entry) => entry.cleanupResources),+ {+ reason: retained+ .map((entry) =>+ String(entry.diagnostics?.["reason"] ?? entry.message),+ )+ .join("; "),+ },+ { operation: KUNA_EXPORT_OPERATION },+ ),+ );+ }++ #await(+ entry: InflightBuild,+ request: KunaProjectRequest,+ ): Promise<Result<KunaProject, AnalysisError>> {+ entry.waiters += 1;+ const onStatus = request.onStatus;+ // Each waiter owns its registration, even when callers reuse a callback.+ const listener =+ onStatus === undefined+ ? undefined+ : (status: KunaExportStatus) => onStatus(status);+ if (listener !== undefined) entry.listeners.add(listener);+ return new Promise((resolve) => {+ let settled = false;+ const leave = () => {+ if (listener !== undefined) entry.listeners.delete(listener);+ entry.waiters -= 1;+ };+ const onAbort = () => {+ if (settled) return;+ settled = true;+ leave();+ if (entry.waiters === 0) entry.controller.abort();+ resolve(err(new AnalysisCancelledError(KUNA_EXPORT_OPERATION)));+ };+ request.signal?.addEventListener("abort", onAbort, { once: true });+ void entry.promise.then((result) => {+ request.signal?.removeEventListener("abort", onAbort);+ if (settled) return;+ settled = true;+ leave();+ resolve(result);+ });+ });+ }++ async #produce(+ key: string,+ request: KunaProjectRequest,+ signal: AbortSignal,+ onStatus: (status: KunaExportStatus) => void,+ ): Promise<Result<KunaProject, AnalysisError>> {+ let staging: string;+ try {+ const existing = await this.lookup(key, signal);+ if (existing !== undefined) return ok(existing);+ await Promise.all(+ ["projects", "staging", "trash", "home"].map((name) =>+ mkdir(join(this.#root, name), { recursive: true, mode: 0o700 }),+ ),+ );+ await this.#sweep(signal);+ staging = await mkdtemp(join(this.#root, "staging", "build-"));+ } catch (cause: unknown) {+ return err(kunaExportFailure(cause, signal));+ }+ const built = await this.#exportAndPublish(+ key,+ staging,+ request,+ signal,+ onStatus,+ ).catch((cause: unknown): StagedResult => ({+ result: err(kunaExportFailure(cause, signal)),+ retainStaging: false,+ }));+ if (built.retainStaging) return built.result;+ let cleanupPath = staging;+ try {+ // Only a proven-stopped build may enter trash. A failed write, crash or+ // lost cleanup identity therefore never makes live staging reclaimable.+ const retired = join(this.#root, "trash", `build-${randomUUID()}`);+ await rename(staging, retired);+ cleanupPath = retired;+ await this.#removeRetired(retired);+ } catch (cause: unknown) {+ if (cause instanceof ProviderCleanupError) return err(cause);+ return err(this.#retainFileCleanup(cleanupPath, cause));+ }+ if (built.result.ok)+ // The entry is published either way; a failed eviction retries on the next publish.+ await this.#evict(key).catch(() => undefined);+ return built.result;+ }++ async #exportAndPublish(+ key: string,+ staging: string,+ request: KunaProjectRequest,+ signal: AbortSignal,+ onStatus: (status: KunaExportStatus) => void,+ ): Promise<StagedResult> {+ const outcome = await exportKunaProject({+ installation: request.installation,+ targetPath: request.targetPath,+ targetSha256: request.targetSha256,+ workspace: staging,+ output: join(staging, "entry", "project"),+ signal,+ onStatus,+ launcher: this.#launcher,+ });+ if (outcome.kind === "retained") {+ this.#retainedProcesses.push(outcome.error);+ return { result: err(outcome.error), retainStaging: true };+ }+ return {+ result: outcome.result.ok+ ? await this.#publish(+ key,+ staging,+ request,+ outcome.result.value,+ signal,+ )+ : outcome.result,+ retainStaging: false,+ };+ }++ /** Record the manifest and publish the staged export under its key. */+ async #publish(+ key: string,+ staging: string,+ request: KunaProjectRequest,+ exported: KunaExport,+ signal: AbortSignal,+ ): Promise<Result<KunaProject, AnalysisError>> {+ const manifest: KunaProjectManifest = {+ layout: CACHE_LAYOUT,+ key,+ inputs: {+ target_sha256: request.targetSha256,+ kuna_sha256: request.installation.sha256,+ kuna_version: request.installation.version,+ jobs: request.installation.configuration.jobs,+ },+ files: exported.files,+ summary: exported.summary,+ created_at: new Date().toISOString(),+ };+ const total = manifestBytes(manifest);+ if (total > this.#maxBytes)+ return err(+ new AnalysisResourceConstraintError(+ KUNA_EXPORT_OPERATION,+ "capacity",+ `This export occupies ${String(total)} bytes, more than the whole Kuna cache may hold.`,+ { cache_max_bytes: this.#maxBytes, export_bytes: total },+ {+ remediationAction:+ "Raise REA_KUNA_CACHE_MAX_BYTES above the export size, or analyze this target with another provider.",+ },+ ),+ );+ await writeFileAtomic(+ join(staging, "entry", "manifest.json"),+ `${JSON.stringify(manifest, null, 2)}\n`,+ { mode: 0o600 },+ );+ const destination = join(this.#root, "projects", key);+ try {+ await rename(join(staging, "entry"), destination);+ } catch (cause: unknown) {+ if (!isPublishedByAnother(cause)) throw cause;+ const winner = await this.lookup(key, signal);+ if (winner !== undefined) return ok(winner);+ throw cause;+ }+ const project = {+ key,+ directory: join(destination, "project"),+ manifest,+ functions: exported.functions,+ inventory: exported.inventory,+ };+ this.#verified.set(key, project);+ return ok(project);+ }++ /**+ * Remove retired resources only. Age and a missing marker cannot establish+ * that a process stopped, so unresolved staging is never swept.+ */+ async #sweep(signal: AbortSignal): Promise<void> {+ for (const name of await readdir(join(this.#root, "trash"))) {+ signal.throwIfAborted();+ await this.#removeRetired(join(this.#root, "trash", name)).catch(+ () => undefined,+ );+ }+ }++ /** Evict least recently used entries above the cap, keeping pinned ones. */+ #evict(keep: string | null): Promise<void> {+ const eviction = this.#eviction.then(() => this.#evictUnpinned(keep));+ this.#eviction = eviction.catch(() => undefined);+ return eviction;+ }++ /** Coalesce deferred reclamation after callers have had a turn to pin results. */+ #scheduleEviction(): void {+ this.#maintenanceRequested = true;+ if (this.#maintenance !== undefined) return;+ const maintenance = (async () => {+ while (this.#maintenanceRequested) {+ await new Promise<void>((resolve) => setImmediate(resolve));+ this.#maintenanceRequested = false;+ await this.#evict(null).catch(() => undefined);+ }+ })();+ this.#maintenance = maintenance;+ void maintenance.then(() => {+ if (this.#maintenance === maintenance) this.#maintenance = undefined;+ if (this.#maintenanceRequested) this.#scheduleEviction();+ });+ }++ async #evictUnpinned(keep: string | null): Promise<void> {+ // A successful build must reach its callers before they can pin its entry.+ // Protect every unfinished build while reading this eviction snapshot.+ const building = new Set([...this.#unfinished].map(({ key }) => key));+ const entries: { key: string; bytes: number; mtimeMs: number }[] = [];+ for (const name of await readdir(join(this.#root, "projects"))) {+ if (!KEY_PATTERN.test(name)) continue;+ const path = join(this.#root, "projects", name);+ const status = await stat(path).catch(() => undefined);+ if (status === undefined) continue;+ const manifest = await this.#readBounded(join(path, "manifest.json"))+ .then(parseManifest)+ .catch(() => undefined);+ // An owned entry without a valid manifest is unusable; evict it first.+ entries.push(+ manifest === undefined+ ? { key: name, bytes: 0, mtimeMs: -1 }+ : {+ key: name,+ bytes: manifestBytes(manifest),+ mtimeMs: status.mtimeMs,+ },+ );+ }+ let total = entries.reduce((sum, entry) => sum + entry.bytes, 0);+ let deferredByBuild = false;+ for (const entry of entries.sort((a, b) => a.mtimeMs - b.mtimeMs)) {+ if (total <= this.#maxBytes && entry.mtimeMs >= 0) break;+ if (building.has(entry.key) || this.#inflight.has(entry.key)) {+ deferredByBuild = true;+ continue;+ }+ if (entry.key === keep || this.#pins.has(entry.key)) continue;+ await this.#discard(entry.key);+ total -= entry.bytes;+ }+ this.#capacity =+ total <= this.#maxBytes+ ? "within_limit"+ : deferredByBuild+ ? "building"+ : "pinned";+ }++ /** Atomically retire one owned entry, then remove it. */+ async #discard(key: string): Promise<void> {+ this.#verified.delete(key);+ const trash = join(this.#root, "trash", `${key}-${randomUUID()}`);+ try {+ await mkdir(join(this.#root, "trash"), { recursive: true, mode: 0o700 });+ await rename(join(this.#root, "projects", key), trash);+ } catch (cause: unknown) {+ if (isMissing(cause)) return;+ throw cause;+ }+ await this.#removeRetired(trash);+ }++ /** Keep each failed removal owned until that path is successfully removed. */+ async #removeRetired(path: string): Promise<void> {+ try {+ await rm(path, { recursive: true, force: true });+ this.#retainedFiles.delete(path);+ } catch (cause: unknown) {+ throw this.#retainFileCleanup(path, cause);+ }+ }++ /** Mark an entry recently used; false when it is no longer published. */+ async #touch(key: string): Promise<boolean> {+ const now = new Date();+ try {+ await utimes(join(this.#root, "projects", key), now, now);+ return true;+ } catch (cause: unknown) {+ // Recency is advisory; only a missing entry changes the answer.+ return !isMissing(cause);+ }+ }++ async #readBounded(path: string): Promise<string> {+ const status = await stat(path);+ if (status.size > MANIFEST_MAX_BYTES)+ throw new RangeError(+ `${path} exceeds ${String(MANIFEST_MAX_BYTES)} bytes`,+ );+ return readFile(path, "utf8");+ }++ #retainFileCleanup(path: string, cause: unknown): ProviderCleanupError {+ const error = new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [path],+ { reason: cause instanceof Error ? cause.message : String(cause) },+ { operation: KUNA_EXPORT_OPERATION, cause },+ );+ this.#retainedFiles.set(path, error);+ return error;+ }+}diff --git a/src/kuna/KunaProjectExport.ts b/src/kuna/KunaProjectExport.tsnew file mode 100644index 000000000..7b45f1c87--- /dev/null+++ b/src/kuna/KunaProjectExport.ts@@ -0,0 +1,466 @@+import { createHash, randomUUID } from "node:crypto";+import { createReadStream, createWriteStream } from "node:fs";+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";+import { basename, join } from "node:path";+import { Transform } from "node:stream";+import { pipeline } from "node:stream/promises";++import { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ AnalysisArtifactChangedError,+ AnalysisCancelledError,+ AnalysisResourceConstraintError,+ AnalysisTimeoutError,+} from "../domain/analysisErrorCore.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { err, ok, type Result } from "../domain/result.js";+import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ OwnedCommandFailure,+ runOwnedCommand,+} from "../process/OwnedCommand.js";+import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";+import type {+ OwnedProviderProcessSpawnOptions,+ ProviderProcessSnapshot,+ SpawnedOwnedProviderProcess,+} from "../process/ProviderProcess.js";+import {+ kunaChildEnvironment,+ type KunaInstallation,+} from "./KunaInstallation.js";+import {+ parseKunaExportSummary,+ parseKunaInventory,+ scanKunaProjectSource,+ type KunaExportSummary,+ type KunaInventoryFunction,+ type KunaProjectFunction,+} from "./KunaProjectFiles.js";+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";++/** Operation name every export and cache failure reports. */+export const KUNA_EXPORT_OPERATION = "kuna:decompile-project";++/** Kuna prints one summary line per export; notes on a large image stay far below this. */+const DIAGNOSTIC_BYTES = 8 * 1024 * 1024;++/**+ * `kuna functions --json` costs ~210 bytes per function; this admits about+ * 600,000 functions, above the 392,814 of the largest image Kuna documents.+ */+const INVENTORY_BYTES = 128 * 1024 * 1024;++const INVENTORY_FILE = "functions.json";++/** Identity of one file an export consists of. */+export interface KunaExportFile {+ readonly path: string;+ readonly bytes: number;+ readonly sha256: string;+}++/** The files of one export, by role. */+export interface KunaExportFiles {+ readonly c: KunaExportFile;+ readonly h: KunaExportFile;+ readonly asm: KunaExportFile;+ readonly readme: KunaExportFile;+ readonly inventory: KunaExportFile;+}++/** One validated export: its files, Kuna's counts and the facts parsed from them. */+export interface KunaExport {+ readonly files: KunaExportFiles;+ readonly summary: KunaExportSummary;+ /** Decompiled function blocks in `.c` order. */+ readonly functions: readonly KunaProjectFunction[];+ /** Every callable entry Kuna found, including imports it does not decompile. */+ readonly inventory: readonly KunaInventoryFunction[];+}++/** The step an export is in; Kuna itself reports no progress until it finishes. */+export interface KunaExportStatus {+ readonly phase: "inventory" | "decompiling" | "sealing";+ /** Callable entries found by the inventory, once known. */+ readonly inventoryFunctions: number | null;+}++/** Test seam for the owned process launcher; production uses the default. */+export type KunaProcessLauncher = (+ options: OwnedProviderProcessSpawnOptions,+) => Promise<SpawnedOwnedProviderProcess>;++/**+ * How an export ended. `retained` means an owned Kuna process could not be+ * proven stopped, so it may still write into the workspace, which therefore+ * stays with the caller's cleanup owner.+ */+export type KunaExportOutcome =+ | {+ readonly kind: "done";+ readonly result: Result<KunaExport, AnalysisError>;+ }+ | { readonly kind: "retained"; readonly error: ProviderCleanupError };++/** One export of a target into a private workspace. */+export interface KunaExportRequest {+ readonly installation: KunaInstallation;+ /** Caller-selected target path; Kuna decompiles a verified copy of it. */+ readonly targetPath: string;+ readonly targetSha256: string;+ /** Private directory for the copy, Kuna's temporary files and its output. */+ readonly workspace: string;+ /** Directory, inside the workspace, that receives the export's files. */+ readonly output: string;+ readonly signal: AbortSignal;+ readonly onStatus: (status: KunaExportStatus) => void;+ readonly launcher?: KunaProcessLauncher | undefined;+}++const message = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);++const isMissing = (cause: unknown): boolean =>+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "ENOENT" || cause.code === "ENOTDIR");++/** Map an unexpected failure to a typed one, preferring cancellation. */+export const kunaExportFailure = (+ cause: unknown,+ signal: AbortSignal,+): AnalysisError => {+ if (signal.aborted)+ return new AnalysisCancelledError(KUNA_EXPORT_OPERATION, { cause });+ if (cause instanceof AnalysisError) return cause;+ return new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {+ cause,+ userMessage: `Kuna project cache failed: ${message(cause)}`,+ });+};++const unusable = (reason: string): KunaExportOutcome => ({+ kind: "done",+ result: err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {+ userMessage: `Kuna's project export is not usable: ${reason}`,+ }),+ ),+});++/** Verify the selected installation at each execution and publication boundary. */+const verifyKunaExecutable = async (+ installation: KunaInstallation,+ signal: AbortSignal,+): Promise<Result<null, ProviderAdapterError>> => {+ const executable = await hashStableFile(installation.executable, signal);+ if (executable.sha256 === installation.sha256) return ok(null);+ return err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {+ userMessage: `${installation.executable} changed after readiness inspection; reopen the target so REA probes the current Kuna executable.`,+ diagnostics: {+ expected_sha256: installation.sha256,+ observed_sha256: executable.sha256,+ },+ }),+ );+};++/**+ * Inventory and export one target with Kuna, then validate the result.+ *+ * Kuna runs on a copy hashed while copying, so the export always describes+ * the digest the caller selected. Both Kuna runs share one deadline.+ */+export const exportKunaProject = async (+ request: KunaExportRequest,+): Promise<KunaExportOutcome> => {+ const { installation, signal } = request;+ const { configuration } = installation;+ const deadline = Date.now() + configuration.projectTimeoutMs;+ const input = join(request.workspace, "input", basename(request.targetPath));+ await mkdir(join(request.workspace, "input"), { mode: 0o700 });+ await mkdir(request.output, { recursive: true, mode: 0o700 });++ const copied = await copyAndHash(request.targetPath, input, signal);+ if (copied !== request.targetSha256)+ return {+ kind: "done",+ result: err(+ new AnalysisArtifactChangedError(+ KUNA_EXPORT_OPERATION,+ request.targetPath,+ "the target no longer matches the digest selected for analysis",+ ),+ ),+ };+ await prepareProcessOwnershipInspection(signal);+ const run = (arguments_: readonly string[], diagnosticBytes: number) =>+ runKuna(request, arguments_, { deadline, diagnosticBytes });++ request.onStatus({ phase: "inventory", inventoryFunctions: null });+ const listed = await run(["functions", input, "--json"], INVENTORY_BYTES);+ if (!listed.ok) return listed.outcome;+ const inventory = parseKunaInventory(listed.snapshot.stdout.text);+ if (!inventory.ok) return unusable(inventory.error);+ if (listed.snapshot.stdout.invalidUtf8 === true)+ return unusable("the function inventory is not valid UTF-8");+ await writeFile(+ join(request.output, INVENTORY_FILE),+ listed.snapshot.stdout.text,+ { mode: 0o600 },+ );++ request.onStatus({+ phase: "decompiling",+ inventoryFunctions: inventory.value.length,+ });+ const exported = await run(+ [+ "decompile-project",+ input,+ "-o",+ request.output,+ "--jobs",+ String(configuration.jobs),+ ],+ DIAGNOSTIC_BYTES,+ );+ if (!exported.ok) return exported.outcome;++ request.onStatus({+ phase: "sealing",+ inventoryFunctions: inventory.value.length,+ });+ const summary = parseKunaExportSummary(exported.snapshot.stdout.text);+ if (summary === undefined)+ return unusable(+ "Kuna did not print its `functions: N ok, M failed` summary.",+ );+ const stem = basename(request.targetPath);+ const names = {+ c: `${stem}.c`,+ h: `${stem}.h`,+ asm: `${stem}.asm`,+ readme: "README.md",+ inventory: INVENTORY_FILE,+ } as const;+ const files: Partial<Record<keyof KunaExportFiles, KunaExportFile>> = {};+ for (const [role, name] of Object.entries(names) as [+ keyof KunaExportFiles,+ string,+ ][]) {+ const path = join(request.output, name);+ const status = await lstat(path).catch((cause: unknown) => {+ if (isMissing(cause)) return undefined;+ throw cause;+ });+ if (status === undefined || !status.isFile())+ return unusable(`Kuna's export has no regular ${name}.`);+ files[role] = { path: name, ...(await hashStableFile(path, signal)) };+ }+ const complete = files as KunaExportFiles;+ const parsed = await readKunaExport(+ request.output,+ complete,+ summary,+ signal,+ );+ if (!parsed.ok) return unusable(parsed.error);+ const identity = await verifyKunaExecutable(installation, signal);+ if (!identity.ok) return { kind: "done", result: identity };+ return {+ kind: "done",+ result: ok({ files: complete, summary, ...parsed.value }),+ };+};++/** Parse an export's function blocks and inventory from its own files. */+export const readKunaExport = async (+ directory: string,+ files: KunaExportFiles,+ summary: KunaExportSummary,+ signal?: AbortSignal,+): Promise<+ Result<+ {+ readonly functions: readonly KunaProjectFunction[];+ readonly inventory: readonly KunaInventoryFunction[];+ },+ string+ >+> => {+ const functions = await scanKunaProjectSource(+ createReadStream(+ join(directory, files.c.path),+ signal === undefined ? {} : { signal },+ ),+ summary,+ );+ if (!functions.ok) return functions;+ const inventory = parseKunaInventory(+ await readFile(join(directory, files.inventory.path), {+ encoding: "utf8",+ ...(signal === undefined ? {} : { signal }),+ }),+ );+ if (!inventory.ok) return inventory;+ return ok({ functions: functions.value, inventory: inventory.value });+};++const runKuna = async (+ request: KunaExportRequest,+ arguments_: readonly string[],+ limits: { readonly deadline: number; readonly diagnosticBytes: number },+): Promise<+ | { readonly ok: true; readonly snapshot: ProviderProcessSnapshot }+ | { readonly ok: false; readonly outcome: KunaExportOutcome }+> => {+ const { installation, signal } = request;+ try {+ const identity = await verifyKunaExecutable(installation, signal);+ if (!identity.ok)+ return { ok: false, outcome: { kind: "done", result: identity } };+ const snapshot = await runOwnedCommand(+ {+ command: installation.executable,+ arguments: arguments_,+ runId: `rea-kuna-${randomUUID()}`,+ // A script's process reports its interpreter, not the configured path.+ ...(installation.script ? { expectedCommand: null } : {}),+ cwd: request.workspace,+ hostEnvironment: kunaChildEnvironment(installation.configuration),+ env: { TMPDIR: request.workspace },+ },+ {+ timeoutMs: Math.max(1, limits.deadline - Date.now()),+ diagnosticBytes: limits.diagnosticBytes,+ },+ {+ signal,+ ...(request.launcher === undefined+ ? {}+ : { launcher: request.launcher }),+ },+ );+ return { ok: true, snapshot };+ } catch (cause: unknown) {+ return {+ ok: false,+ outcome: commandFailure(cause, request, arguments_[0] ?? "", limits),+ };+ }+};++/** Copy the target into the workspace and return the SHA-256 of exactly the bytes copied. */+const copyAndHash = async (+ source: string,+ destination: string,+ signal: AbortSignal,+): Promise<string> => {+ const hash = createHash("sha256");+ await pipeline(+ createReadStream(source),+ new Transform({+ transform(chunk: Buffer, _encoding, callback) {+ hash.update(chunk);+ callback(null, chunk);+ },+ }),+ createWriteStream(destination, { flags: "wx", mode: 0o600 }),+ { signal },+ );+ return hash.digest("hex");+};++/** Map an owned-command failure to its typed error, keeping unproven cleanup owned. */+const commandFailure = (+ cause: unknown,+ request: KunaExportRequest,+ subcommand: string,+ limits: { readonly diagnosticBytes: number },+): KunaExportOutcome => {+ const { installation, signal } = request;+ if (!(cause instanceof OwnedCommandFailure))+ return {+ kind: "done",+ result: err(+ signal.aborted+ ? new AnalysisCancelledError(KUNA_EXPORT_OPERATION, { cause })+ : new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {+ cause,+ userMessage: `Cannot run ${installation.executable}: ${message(cause)}`,+ }),+ ),+ };+ const snapshot = cause.snapshot;+ const capturedOutput =+ snapshot === null+ ? undefined+ : {+ // An inventory is evidence-sized, not diagnostic-sized; keep only its tail.+ stdout: snapshot.stdout.text.slice(-4096),+ stderr: snapshot.stderr.text,+ truncated:+ snapshot.diagnosticTruncated === true ||+ snapshot.outputIncomplete === true ||+ snapshot.stdout.text.length > 4096,+ exit_code: snapshot.exitCode ?? null,+ signal: snapshot.signal ?? null,+ };+ const details = {+ cause,+ ...(capturedOutput === undefined ? {} : { capturedOutput }),+ };+ if (cause.cleanupFailure !== null)+ return {+ kind: "retained",+ error: new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [...cause.resources, request.workspace],+ { reason: cause.cleanupFailure },+ { operation: KUNA_EXPORT_OPERATION, cause },+ ),+ };+ if (cause.reason === "cancelled")+ return {+ kind: "done",+ result: err(new AnalysisCancelledError(KUNA_EXPORT_OPERATION, details)),+ };+ if (cause.reason === "timeout")+ return {+ kind: "done",+ result: err(+ new AnalysisTimeoutError(+ KUNA_EXPORT_OPERATION,+ installation.configuration.projectTimeoutMs,+ details,+ ),+ ),+ };+ if (cause.reason === "output-limit")+ return {+ kind: "done",+ result: err(+ new AnalysisResourceConstraintError(+ KUNA_EXPORT_OPERATION,+ "capacity",+ `kuna ${subcommand} wrote more than ${String(limits.diagnosticBytes)} bytes of output; the export was not retained.`,+ { output_limit_bytes: limits.diagnosticBytes },+ details,+ ),+ ),+ };+ const exitCode = capturedOutput?.exit_code;+ return {+ kind: "done",+ result: err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {+ ...details,+ userMessage: `kuna ${subcommand} failed${exitCode === undefined || exitCode === null ? "" : ` with exit code ${String(exitCode)}`}: ${capturedOutput?.stderr.trim().split("\n").at(-1) ?? cause.message}`,+ }),+ ),+ };+};diff --git a/src/kuna/KunaProjectFiles.ts b/src/kuna/KunaProjectFiles.tsnew file mode 100644index 000000000..9f0714f58--- /dev/null+++ b/src/kuna/KunaProjectFiles.ts@@ -0,0 +1,189 @@+import { z } from "zod";++import { err, ok, type Result } from "../domain/result.js";++/**+ * One function block in a `kuna decompile-project` `.c` file. The span covers+ * its `// Function:` header through the blank line that ends the block, which+ * is how REA serves one function without reading the whole file.+ */+export interface KunaProjectFunction {+ readonly name: string;+ /** Kuna's display address, a lowercase `0x…` virtual address. */+ readonly address: string;+ readonly cOffset: number;+ readonly cLength: number;+ /** Kuna's own failure for this function; its block is then the header alone. */+ readonly error: string | null;+}++// Rendered by kuna-console's `render_c`: `// Function: {name} @ 0x{addr:x}`,+// or `... @ 0x{addr:x} (error: {message})` for a failed function. A name+// can itself contain " @ ", so the address is the last such field.+const HEADER = /^\/\/ Function: (.+) @ (0x[0-9a-f]+)(?: {2}\(error: (.*)\))?$/u;+const HEADER_PREFIX = "// Function: ";++/** Kuna's completed-export summary on stdout: `functions: N ok, M failed`. */+const SUMMARY = /functions: (\d+) ok, (\d+) failed/u;++/** Function counts Kuna reported for a finished export. */+export interface KunaExportSummary {+ readonly decompiled: number;+ readonly failed: number;+}++/** Read the completed-file summary Kuna prints after finalizing an export. */+export const parseKunaExportSummary = (+ stdout: string,+): KunaExportSummary | undefined => {+ const match = SUMMARY.exec(stdout);+ if (match?.[1] === undefined || match[2] === undefined) return undefined;+ return { decompiled: Number(match[1]), failed: Number(match[2]) };+};++/** A header line longer than this is not one Kuna wrote. */+const MAX_HEADER_BYTES = 64 * 1024;+const PREFIX_BYTES = Buffer.from(HEADER_PREFIX);++interface Header {+ readonly name: string;+ readonly address: string;+ readonly error: string | null;+ readonly offset: number;+}++/**+ * Split a finished export's `.c` into its function blocks, reading it as a+ * stream so a very large export is never held in memory.+ *+ * The `#include` preamble precedes the first header. The header count must+ * equal the functions Kuna reported, and every address must be distinct; an+ * export that fails either check is not a usable function inventory.+ */+export const scanKunaProjectSource = async (+ chunks: AsyncIterable<Buffer>,+ summary: KunaExportSummary,+): Promise<Result<readonly KunaProjectFunction[], string>> => {+ const headers: Header[] = [];+ let offset = 0;+ let lineStart = 0;+ // Bytes of the current line, kept only while it may still be a header.+ let line: Buffer[] | undefined = [];+ let lineBytes = 0;+ const endLine = (): string | undefined => {+ if (line === undefined) return undefined;+ const text = Buffer.concat(line).toString("utf8");+ if (!text.startsWith(HEADER_PREFIX)) return undefined;+ const match = HEADER.exec(text);+ if (match?.[1] === undefined || match[2] === undefined)+ return `unrecognized function header at byte ${String(lineStart)}`;+ headers.push({+ name: match[1],+ address: match[2],+ error: match[3] ?? null,+ offset: lineStart,+ });+ return undefined;+ };+ for await (const chunk of chunks) {+ let position = 0;+ while (position < chunk.length) {+ const newline = chunk.indexOf(0x0a, position);+ const end = newline === -1 ? chunk.length : newline;+ if (line !== undefined) {+ const segment = chunk.subarray(position, end);+ line.push(segment);+ lineBytes += segment.length;+ const seen = Buffer.concat(line).subarray(0, PREFIX_BYTES.length);+ if (!PREFIX_BYTES.subarray(0, seen.length).equals(seen))+ line = undefined;+ else if (lineBytes > MAX_HEADER_BYTES)+ return err(+ `function header at byte ${String(lineStart)} is too long`,+ );+ }+ if (newline === -1) break;+ const failure = endLine();+ if (failure !== undefined) return err(failure);+ position = newline + 1;+ lineStart = offset + position;+ line = [];+ lineBytes = 0;+ }+ offset += chunk.length;+ }+ const failure = endLine();+ if (failure !== undefined) return err(failure);+ const total = offset;+ const expected = summary.decompiled + summary.failed;+ if (headers.length !== expected)+ return err(+ `the .c holds ${String(headers.length)} function headers but Kuna reported ${String(expected)} functions`,+ );+ const failed = headers.filter(({ error }) => error !== null).length;+ if (failed !== summary.failed)+ return err(+ `the .c marks ${String(failed)} failed functions but Kuna reported ${String(summary.failed)}`,+ );+ const addresses = new Set<string>();+ const functions: KunaProjectFunction[] = [];+ for (const [index, header] of headers.entries()) {+ if (addresses.has(header.address))+ return err(`the .c repeats address ${header.address}`);+ addresses.add(header.address);+ const end = headers[index + 1]?.offset ?? total;+ functions.push({+ name: header.name,+ address: header.address,+ cOffset: header.offset,+ cLength: end - header.offset,+ error: header.error,+ });+ }+ return ok(functions);+};++const inventorySchema = z.object({+ functions: z.array(+ z.object({+ name: z.string(),+ address_hex: z.string().regex(/^0x[0-9a-f]+$/u),+ aliases: z.array(z.string()),+ size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),+ }),+ ),+});++/** One callable entry from `kuna functions --json`, including imports Kuna does not decompile. */+export interface KunaInventoryFunction {+ readonly name: string;+ readonly address: string;+ readonly aliases: readonly string[];+ /** Inventory extent: an upper bound clipped at the next entry, or 0 when unmeasured. */+ readonly size: number;+}++/** Parse the callable-symbol inventory `kuna functions --json` writes. */+export const parseKunaInventory = (+ text: string,+): Result<readonly KunaInventoryFunction[], string> => {+ let value: unknown;+ try {+ value = JSON.parse(text);+ } catch {+ return err("the function inventory is not JSON");+ }+ const parsed = inventorySchema.safeParse(value);+ if (!parsed.success)+ return err(+ `the function inventory does not match Kuna's document: ${parsed.error.issues[0]?.message ?? "invalid"}`,+ );+ return ok(+ parsed.data.functions.map((entry) => ({+ name: entry.name,+ address: entry.address_hex,+ aliases: entry.aliases,+ size: entry.size,+ })),+ );+};diff --git a/src/kuna/KunaRelease.ts b/src/kuna/KunaRelease.tsnew file mode 100644index 000000000..e1ff9b831--- /dev/null+++ b/src/kuna/KunaRelease.ts@@ -0,0 +1,16 @@+/** Kuna release whose CLI and project layout REA verified; others report as unverified. */+export const KUNA_VERIFIED_VERSION = "1.833";++/** Stable provider ID shared by readiness, doctor and Evidence. */+export const KUNA_PROVIDER_ID = "kuna";++/** Remediation when `REA_KUNA_COMMAND` is missing or not an absolute path. */+export const KUNA_COMMAND_REMEDIATION = `Set REA_KUNA_COMMAND to the absolute path of a caller-supplied kuna executable (verified with ${KUNA_VERIFIED_VERSION}). REA does not download, install or update Kuna.`;++/** Remediation when the host cannot supervise a Kuna process tree. */+export const KUNA_UNSUPPORTED_HOST_REMEDIATION =+ "Use Linux or macOS for the Kuna provider. Windows process-tree ownership for Kuna is not verified.";++/** Remediation when `kuna --version` cannot establish the installed release. */+export const KUNA_VERSION_PROBE_REMEDIATION =+ "Run the selected executable with --version: it must exit promptly and print `kuna <major>.<minor>`.";diff --git a/tests/boundary/providers/kuna/fakeKuna.ts b/tests/boundary/providers/kuna/fakeKuna.tsnew file mode 100644index 000000000..24c04b1a9--- /dev/null+++ b/tests/boundary/providers/kuna/fakeKuna.ts@@ -0,0 +1,125 @@+import { readFile, writeFile } from "node:fs/promises";+import { join } from "node:path";++/** One function the fake exports; `error` renders Kuna's failed-function header. */+export interface FakeKunaFunction {+ readonly name: string;+ readonly addr: string;+ readonly error?: string;+}++/** Scripted behavior of the fake `kuna` executable for one test. */+export interface FakeKunaBehavior {+ /** Text printed by `--version`; `exit` fails the probe instead. */+ readonly version?:+ | { readonly stdout: string }+ | { readonly exit: number }+ | { readonly ignoreTerm: true };+ readonly inventory?: "ok" | "not-json" | "hang";+ readonly project?:+ | "ok"+ | "exit-failure"+ | "hang"+ | "miscounted"+ | "silent"+ | "block-manifest";+ readonly functions?: readonly FakeKunaFunction[];+ /** Extra `.asm` bytes, for capacity tests. */+ readonly asmPadding?: number;+ /** Milliseconds the export takes before writing its files. */+ readonly delayMs?: number;+}++/**+ * The fake reads its behavior from `<script>.json` and appends one line per+ * invocation to `<script>.calls`. REA gives Kuna children no PATH, so the+ * shebang names this Node binary directly. Output formats follow Kuna 1.833:+ * `functions --json` and the `// Function:` headers of `render_c`.+ */+const SCRIPT = String.raw`+const fs = require("node:fs");+const path = require("node:path");+const behavior = JSON.parse(fs.readFileSync(__filename + ".json", "utf8"));+fs.appendFileSync(__filename + ".calls", JSON.stringify({ pid: process.pid, argv: process.argv.slice(2), home: process.env.HOME, xdg: process.env.XDG_CACHE_HOME, path: process.env.PATH ?? null }) + "\n");+const args = process.argv.slice(2);+const functions = behavior.functions ?? [{ name: "main", addr: "0x1000" }, { name: "helper", addr: "0x1040" }];+const hang = () => setInterval(() => {}, 1000);+if (args[0] === "--version") {+ const version = behavior.version ?? { stdout: "kuna 1.833\n" };+ if ("exit" in version) { process.stderr.write("version probe failed\n"); process.exit(version.exit); }+ if ("ignoreTerm" in version) { process.on("SIGTERM", () => {}); hang(); }+ else process.stdout.write(version.stdout);+} else if (args[0] === "functions") {+ const mode = behavior.inventory ?? "ok";+ if (mode === "hang") hang();+ else if (mode === "not-json") process.stdout.write("functions: 2\n");+ else {+ const listed = [...functions, { name: "puts", addr: "0x2000" }].map((fn) => ({ name: fn.name, address: parseInt(fn.addr, 16), address_hex: fn.addr, aliases: [], object_location: null, size: fn.name === "puts" ? 0 : 16 }));+ process.stdout.write(JSON.stringify({ binary: args[1], count: listed.length, total: listed.length, error: null, functions: listed }, null, 2) + "\n");+ }+} else if (args[0] === "decompile-project") {+ const input = args[1];+ const output = args[args.indexOf("-o") + 1];+ const stem = path.basename(input);+ const mode = behavior.project ?? "ok";+ if (mode === "hang") hang();+ else if (mode === "exit-failure") { process.stderr.write("error: not in recognized object file format\n"); process.exit(1); }+ else setTimeout(() => {+ fs.mkdirSync(output, { recursive: true });+ let c = '#include "' + stem + '.h"\n\n';+ functions.forEach((fn, index) => {+ c += fn.error === undefined+ ? "// Function: " + fn.name + " @ " + fn.addr + "\nint " + fn.name + "(void)\n{\n return " + index + ";\n}\n\n"+ : "// Function: " + fn.name + " @ " + fn.addr + " (error: " + fn.error + ")\n\n";+ });+ fs.writeFileSync(path.join(output, stem + ".c"), c);+ fs.writeFileSync(path.join(output, stem + ".h"), "#pragma once\n");+ fs.writeFileSync(path.join(output, stem + ".asm"), "; asm\n" + "x".repeat(behavior.asmPadding ?? 0));+ fs.writeFileSync(path.join(output, "README.md"), "# " + stem + "\n");+ // Occupy the manifest path so REA's publication write fails.+ if (mode === "block-manifest") fs.mkdirSync(path.join(output, "..", "manifest.json"));+ const failed = functions.filter((fn) => fn.error !== undefined).length;+ const reported = mode === "miscounted" ? functions.length + 1 : functions.length - failed;+ if (mode !== "silent") process.stdout.write("wrote " + output + ": " + stem + ".c (" + c.length + " bytes); functions: " + reported + " ok, " + failed + " failed\n");+ }, behavior.delayMs ?? 0);+} else {+ process.stderr.write("unexpected command\n");+ process.exit(2);+}+`;++/** Write a fake `kuna` into a directory and return its path. */+export const writeFakeKuna = async (+ directory: string,+ behavior: FakeKunaBehavior = {},+): Promise<string> => {+ const path = join(directory, "kuna");+ await writeFile(path, `#!${process.execPath}\n${SCRIPT}`, { mode: 0o755 });+ await writeFile(`${path}.json`, JSON.stringify(behavior));+ return path;+};++/** Replace the scripted behavior of an existing fake. */+export const setFakeKunaBehavior = (+ path: string,+ behavior: FakeKunaBehavior,+): Promise<void> => writeFile(`${path}.json`, JSON.stringify(behavior));++/** Invocations the fake recorded, oldest first. */+export const fakeKunaCalls = async (+ path: string,+): Promise<+ readonly {+ readonly pid: number;+ readonly argv: readonly string[];+ readonly home: string;+ readonly xdg: string;+ readonly path: string | null;+ }[]+> => {+ const text = await readFile(`${path}.calls`, "utf8").catch(() => "");+ return text+ .split("\n")+ .filter((line) => line.length > 0)+ .map((line) => JSON.parse(line) as never);+};diff --git a/tests/boundary/providers/kuna/kunaDoctor.test.ts b/tests/boundary/providers/kuna/kunaDoctor.test.tsnew file mode 100644index 000000000..ea648e6be--- /dev/null+++ b/tests/boundary/providers/kuna/kunaDoctor.test.ts@@ -0,0 +1,136 @@+import { mkdir, writeFile } from "node:fs/promises";+import { join } from "node:path";++import { expect, it as test } from "vitest";++import { inspectKunaProvider } from "../../../../src/kuna/KunaDoctor.js";+import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import { writeFakeKuna } from "./fakeKuna.js";++const it = test.skipIf(process.platform === "win32");++it("reports an unconfigured Kuna as a missing optional engine", async () => {+ expect(await inspectKunaProvider({})).toMatchObject({+ id: "kuna",+ configured: false,+ available: false,+ providerVersion: null,+ registrationEnvironment: {},+ checks: [+ {+ name: "installation",+ ok: false,+ code: "not_configured",+ classification: "missing_analysis_engine",+ },+ ],+ });+});++it("publishes the caller's explicit settings once the installation validates", async () => {+ const root = await createTestTempDirectory("rea-kuna-doctor-");+ const kuna = await writeFakeKuna(root);+ const cache = join(root, "cache");++ const inspection = await inspectKunaProvider({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: cache,+ REA_KUNA_JOBS: "4",+ UNRELATED: "not published",+ });++ expect(inspection).toMatchObject({+ configured: true,+ available: true,+ providerVersion: "1.833",+ registrationEnvironment: {+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: cache,+ REA_KUNA_JOBS: "4",+ },+ checks: [+ { name: "installation", ok: true, details: { version: "1.833" } },+ {+ name: "cache",+ ok: true,+ detail: `REA creates the Kuna project cache at ${cache} on first use.`,+ },+ ],+ });+ expect(Object.keys(inspection.registrationEnvironment)).toHaveLength(3);+});++it("flags an unverified release without failing the installation", async () => {+ const root = await createTestTempDirectory("rea-kuna-doctor-version-");+ const kuna = await writeFakeKuna(root, {+ version: { stdout: "kuna 1.950\n" },+ });++ const inspection = await inspectKunaProvider({ REA_KUNA_COMMAND: kuna });++ expect(inspection.checks[0]).toMatchObject({+ ok: true,+ detail: expect.stringContaining(+ "this release's project layout is unverified",+ ),+ });+});++it("reports a cache root REA cannot use without creating anything", async () => {+ const root = await createTestTempDirectory("rea-kuna-doctor-cache-");+ const kuna = await writeFakeKuna(root);+ const occupied = join(root, "occupied");+ await writeFile(occupied, "not a directory");+ const existing = join(root, "existing");+ await mkdir(existing);++ const blocked = await inspectKunaProvider({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: occupied,+ });+ const ready = await inspectKunaProvider({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: existing,+ });++ expect(blocked.checks[1]).toMatchObject({+ name: "cache",+ ok: false,+ code: "open_options_invalid",+ });+ expect(ready.checks[1]).toMatchObject({+ name: "cache",+ ok: true,+ detail: expect.stringContaining(`cached in ${existing}`),+ });+});++it("reports a cache root REA cannot create under its nearest existing parent", async () => {+ const root = await createTestTempDirectory("rea-kuna-doctor-create-");+ const kuna = await writeFakeKuna(root);+ const readOnly = join(root, "read-only");+ await mkdir(readOnly, { mode: 0o500 });+ const occupied = join(root, "occupied");+ await writeFile(occupied, "not a directory");++ const underReadOnly = await inspectKunaProvider({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: join(readOnly, "nested", "cache"),+ });+ const underFile = await inspectKunaProvider({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: join(occupied, "cache"),+ });++ expect(underReadOnly.checks[1]).toMatchObject({+ name: "cache",+ ok: false,+ detail: expect.stringContaining(`${readOnly} is not writable`),+ });+ expect(underFile.checks[1]).toMatchObject({+ name: "cache",+ ok: false,+ // stat reports ENOTDIR for a path beneath a regular file.+ detail: expect.stringContaining("not a directory"),+ });+});diff --git a/tests/boundary/providers/kuna/kunaInstallation.test.ts b/tests/boundary/providers/kuna/kunaInstallation.test.tsnew file mode 100644index 000000000..13b98bcba--- /dev/null+++ b/tests/boundary/providers/kuna/kunaInstallation.test.ts@@ -0,0 +1,212 @@+import { createHash } from "node:crypto";+import { chmod, readFile, realpath, symlink } from "node:fs/promises";+import { join } from "node:path";++import { expect, it as test } from "vitest";++import { readKunaConfiguration } from "../../../../src/kuna/KunaConfiguration.js";+import { inspectKunaInstallation } from "../../../../src/kuna/KunaInstallation.js";+import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import { fakeKunaCalls, writeFakeKuna } from "./fakeKuna.js";++const it = test.skipIf(process.platform === "win32");++it("identifies a caller-selected kuna by version and digest", async () => {+ const root = await createTestTempDirectory("rea-kuna-install-");+ const kuna = await writeFakeKuna(root);+ const link = join(root, "current-kuna");+ await symlink(kuna, link);++ const result = await inspectKunaInstallation({+ REA_KUNA_COMMAND: link,+ REA_KUNA_CACHE_DIR: join(root, "cache"),+ });++ expect(result).toMatchObject({+ ok: true,+ value: {+ configuration: { command: link, cacheRoot: join(root, "cache") },+ executable: await realpath(kuna),+ version: "1.833",+ verified: true,+ // A `#!` launcher reports its interpreter; ownership checks must not expect the path.+ script: true,+ sha256: createHash("sha256")+ .update(await readFile(kuna))+ .digest("hex"),+ },+ });+ // The probe runs inside REA's cache home with no inherited PATH.+ expect(await fakeKunaCalls(kuna)).toEqual([+ {+ pid: expect.any(Number),+ argv: ["--version"],+ home: join(root, "cache", "home"),+ xdg: join(root, "cache", "home", ".cache"),+ path: null,+ },+ ]);+});++it("accepts another release but reports it as unverified", async () => {+ const root = await createTestTempDirectory("rea-kuna-unverified-");+ const kuna = await writeFakeKuna(root, {+ version: { stdout: "kuna 1.900\n" },+ });++ const result = await inspectKunaInstallation({ REA_KUNA_COMMAND: kuna });++ expect(result).toMatchObject({+ ok: true,+ value: { version: "1.900", verified: false },+ });+});++it("refuses a version line it cannot recognize", async () => {+ const root = await createTestTempDirectory("rea-kuna-garbled-");+ const kuna = await writeFakeKuna(root, {+ version: { stdout: "Kuna decompiler, built today\n" },+ });++ expect(+ await inspectKunaInstallation({ REA_KUNA_COMMAND: kuna }),+ ).toMatchObject({+ ok: false,+ error: {+ code: "version_unresolved",+ diagnostics: { stdout: "Kuna decompiler, built today\n" },+ },+ });+});++it("reports a failed version probe with its exit status", async () => {+ const root = await createTestTempDirectory("rea-kuna-probe-exit-");+ const kuna = await writeFakeKuna(root, { version: { exit: 3 } });++ expect(+ await inspectKunaInstallation({ REA_KUNA_COMMAND: kuna }),+ ).toMatchObject({+ ok: false,+ error: {+ code: "version_unresolved",+ reason: expect.stringContaining("version probe failed"),+ diagnostics: { exit_code: 3, killed: false },+ },+ });+});++it("reports a missing or non-executable command as executable_missing", async () => {+ const root = await createTestTempDirectory("rea-kuna-missing-");+ const kuna = await writeFakeKuna(root);+ await chmod(kuna, 0o644);++ for (const command of [kuna, join(root, "absent"), root])+ expect(+ await inspectKunaInstallation({ REA_KUNA_COMMAND: command }),+ ).toMatchObject({+ ok: false,+ error: { code: "executable_missing", diagnostics: { command } },+ });+});++it("distinguishes an unset command from an invalid one", async () => {+ expect(await inspectKunaInstallation({})).toMatchObject({+ ok: false,+ error: { code: "not_configured", diagnostics: { configured: false } },+ });+ expect(+ await inspectKunaInstallation({ REA_KUNA_COMMAND: "bin/kuna" }),+ ).toMatchObject({+ ok: false,+ error: {+ code: "open_options_invalid",+ diagnostics: { configured: true, setting: "REA_KUNA_COMMAND" },+ },+ });+});++it("declares Windows hosts unsupported before touching the command", async () => {+ expect(+ await inspectKunaInstallation(+ { REA_KUNA_COMMAND: "/opt/kuna/kuna" },+ { platform: "win32" },+ ),+ ).toMatchObject({ ok: false, error: { code: "unsupported_host" } });+});++it("parses cache, timeout and job settings at the configuration boundary", () => {+ const environment = {+ REA_KUNA_COMMAND: "/opt/kuna/kuna",+ HOME: "/home/analyst",+ };+ expect(readKunaConfiguration(environment, "linux")).toMatchObject({+ ok: true,+ value: {+ cacheRoot: "/home/analyst/.cache/rea/kuna",+ cacheMaxBytes: 4 * 1024 ** 3,+ projectTimeoutMs: 1_800_000,+ // Kuna's reference answer is a serial export; more jobs change results.+ jobs: 1,+ },+ });+ expect(+ readKunaConfiguration(+ { ...environment, XDG_CACHE_HOME: "/var/cache/analyst" },+ "linux",+ ),+ ).toMatchObject({ value: { cacheRoot: "/var/cache/analyst/rea/kuna" } });+ expect(readKunaConfiguration(environment, "darwin")).toMatchObject({+ value: { cacheRoot: "/home/analyst/Library/Caches/rea/kuna" },+ });+ expect(+ readKunaConfiguration(+ {+ ...environment,+ REA_KUNA_CACHE_MAX_BYTES: "2097152",+ REA_KUNA_PROJECT_TIMEOUT_MS: "60000",+ REA_KUNA_JOBS: "3",+ },+ "linux",+ ),+ ).toMatchObject({+ value: { cacheMaxBytes: 2097152, projectTimeoutMs: 60000, jobs: 3 },+ });+ for (const [setting, value] of [+ ["REA_KUNA_CACHE_DIR", "relative/cache"],+ ["REA_KUNA_CACHE_MAX_BYTES", "1024"],+ ["REA_KUNA_CACHE_MAX_BYTES", "4GiB"],+ ["REA_KUNA_PROJECT_TIMEOUT_MS", "0"],+ ["REA_KUNA_JOBS", "33"],+ ["REA_KUNA_JOBS", "0"],+ ] as const)+ expect(+ readKunaConfiguration({ ...environment, [setting]: value }, "linux"),+ ).toMatchObject({+ ok: false,+ error: { code: "open_options_invalid", setting },+ });+});++it("stops a version probe that ignores SIGTERM instead of waiting on it", async () => {+ const root = await createTestTempDirectory("rea-kuna-probe-term-");+ const kuna = await writeFakeKuna(root, { version: { ignoreTerm: true } });+ const started = Date.now();++ const result = await inspectKunaInstallation(+ { REA_KUNA_COMMAND: kuna },+ // Long enough for Node to start the fake and install its SIGTERM handler.+ { probeTimeoutMs: 1500 },+ );++ expect(result).toMatchObject({+ ok: false,+ error: {+ code: "version_unresolved",+ diagnostics: { killed: true, deadline_ms: 1500 },+ },+ });+ // The deadline plus ExecFileOutput's bounded kill grace, never an open-ended wait.+ expect(Date.now() - started).toBeLessThan(15_000);+ const pid = (await fakeKunaCalls(kuna))[0]?.pid ?? 0;+ expect(() => process.kill(pid, 0)).toThrow();+}, 20_000);diff --git a/tests/boundary/providers/kuna/kunaProjectCache.test.ts b/tests/boundary/providers/kuna/kunaProjectCache.test.tsnew file mode 100644index 000000000..0885029ea--- /dev/null+++ b/tests/boundary/providers/kuna/kunaProjectCache.test.ts@@ -0,0 +1,704 @@+import { createHash } from "node:crypto";+import {+ appendFile,+ chmod,+ mkdir,+ readdir,+ readFile,+ rename,+ rm,+ utimes,+ writeFile,+} from "node:fs/promises";+import { join } from "node:path";++import { expect, it as test } from "vitest";++import { inspectKunaInstallation } from "../../../../src/kuna/KunaInstallation.js";+import { cleanupOwnedProcessGroup } from "../../../../src/process/ProcessOwnership.js";+import { spawnOwnedProviderProcess } from "../../../../src/process/ProviderProcess.js";+import type { KunaInstallation } from "../../../../src/kuna/KunaInstallation.js";+import {+ KunaProjectCache,+ kunaProjectKey,+} from "../../../../src/kuna/KunaProjectCache.js";+import type { KunaExportStatus } from "../../../../src/kuna/KunaProjectExport.js";+import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import {+ fakeKunaCalls,+ setFakeKunaBehavior,+ writeFakeKuna,+ type FakeKunaBehavior,+} from "./fakeKuna.js";++const it = test.skipIf(process.platform === "win32");++interface Target {+ readonly targetPath: string;+ readonly targetSha256: string;+}++const fixture = async (+ prefix: string,+ behavior: FakeKunaBehavior = {},+ options: {+ readonly maxBytes?: number;+ readonly environment?: Readonly<Record<string, string>>;+ } = {},+) => {+ const root = await createTestTempDirectory(prefix);+ const kuna = await writeFakeKuna(root, behavior);+ const installed = await inspectKunaInstallation({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: join(root, "cache"),+ ...options.environment,+ });+ if (!installed.ok) throw new Error(installed.error.reason);+ return {+ kuna,+ installation: installed.value,+ cacheRoot: installed.value.configuration.cacheRoot,+ cache: newCache(installed.value, options.maxBytes),+ target: async (name: string, content = name): Promise<Target> => {+ const targetPath = join(root, name);+ await writeFile(targetPath, content);+ return {+ targetPath,+ targetSha256: createHash("sha256").update(content).digest("hex"),+ };+ },+ };+};++const newCache = (installation: KunaInstallation, maxBytes = 64 * 1024 ** 2) =>+ new KunaProjectCache(installation.configuration.cacheRoot, {+ maxBytes,+ });++const keyOf = (installation: KunaInstallation, target: Target) =>+ kunaProjectKey({+ targetSha256: target.targetSha256,+ kunaSha256: installation.sha256,+ kunaVersion: installation.version,+ jobs: installation.configuration.jobs,+ });++const callsOf = async (kuna: string, subcommand: string) =>+ (await fakeKunaCalls(kuna)).filter(({ argv }) => argv[0] === subcommand);++const entries = (cacheRoot: string, area: string) =>+ readdir(join(cacheRoot, area)).catch(() => []);++const processGone = (pid: number): boolean => {+ try {+ process.kill(pid, 0);+ return false;+ } catch {+ return true;+ }+};++it("publishes a verified export and serves later requests from the cache", async () => {+ const { kuna, installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-cache-",+ {+ functions: [+ { name: "main", addr: "0x1000" },+ { name: "parse @ table", addr: "0x1040" },+ {+ name: "broken",+ addr: "0x1080",+ error: "Exceeded the instruction budget",+ },+ ],+ },+ { environment: { REA_KUNA_JOBS: "1" } },+ );+ const input = await target("program");++ const built = await cache.build({ installation, ...input });++ expect(built).toMatchObject({+ ok: true,+ value: {+ key: keyOf(installation, input),+ manifest: {+ layout: 1,+ inputs: {+ target_sha256: input.targetSha256,+ kuna_sha256: installation.sha256,+ kuna_version: "1.833",+ jobs: 1,+ },+ summary: { decompiled: 2, failed: 1 },+ },+ functions: [+ { name: "main", address: "0x1000", error: null },+ // A name may itself contain " @ "; the address is the last field.+ { name: "parse @ table", address: "0x1040", error: null },+ {+ name: "broken",+ address: "0x1080",+ error: "Exceeded the instruction budget",+ },+ ],+ // The inventory also names imports Kuna does not decompile.+ inventory: [+ { name: "main", address: "0x1000", size: 16 },+ { name: "parse @ table", address: "0x1040", size: 16 },+ { name: "broken", address: "0x1080", size: 16 },+ { name: "puts", address: "0x2000", size: 0 },+ ],+ },+ });+ if (!built.ok) throw built.error;+ const [main, , broken] = built.value.functions;+ const c = await readFile(join(built.value.directory, "program.c"));+ const slice = (span: typeof main) =>+ c+ .subarray(span?.cOffset, (span?.cOffset ?? 0) + (span?.cLength ?? 0))+ .toString("utf8");+ expect(slice(main)).toBe(+ "// Function: main @ 0x1000\nint main(void)\n{\n return 0;\n}\n\n",+ );+ expect(slice(broken)).toBe(+ "// Function: broken @ 0x1080 (error: Exceeded the instruction budget)\n\n",+ );++ // Kuna listed and decompiled a staged copy from REA's own HOME, in reference mode.+ const [listing] = await callsOf(kuna, "functions");+ const [exported] = await callsOf(kuna, "decompile-project");+ expect(listing?.argv).toEqual(["functions", exported?.argv[1], "--json"]);+ expect(exported?.argv.slice(2)).toEqual([+ "-o",+ expect.stringContaining(join("cache", "staging")),+ "--jobs",+ "1",+ ]);+ expect(exported?.argv[1]).not.toBe(input.targetPath);+ expect(exported?.home).toBe(join(cacheRoot, "home"));+ expect(await entries(cacheRoot, "staging")).toEqual([]);++ // The same process and a fresh one both reuse the published entry.+ await cache.build({ installation, ...input });+ expect(await newCache(installation).lookup(built.value.key)).toMatchObject({+ functions: built.value.functions,+ inventory: built.value.inventory,+ });+ expect(await callsOf(kuna, "decompile-project")).toHaveLength(1);+});++it("shares one Kuna run between concurrent requests for one export", async () => {+ const { kuna, installation, cache, target } = await fixture(+ "rea-kuna-singleflight-",+ { delayMs: 300 },+ );+ const input = await target("program");++ const [first, second] = await Promise.all([+ cache.build({ installation, ...input }),+ cache.build({ installation, ...input }),+ ]);++ expect(first.ok && second.ok).toBe(true);+ if (first.ok && second.ok)+ expect(first.value.directory).toBe(second.value.directory);+ expect(await callsOf(kuna, "decompile-project")).toHaveLength(1);+});++it("stops the run only when every waiting request is cancelled", async () => {+ const { kuna, installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-cancel-",+ { project: "hang" },+ );+ const input = await target("program");+ const firstCaller = new AbortController();+ const secondCaller = new AbortController();++ const first = cache.build({+ installation,+ ...input,+ signal: firstCaller.signal,+ });+ const second = cache.build({+ installation,+ ...input,+ signal: secondCaller.signal,+ });+ await expect.poll(() => callsOf(kuna, "decompile-project")).toHaveLength(1);+ const pid = (await callsOf(kuna, "decompile-project"))[0]?.pid ?? 0;++ firstCaller.abort();+ expect(await first).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ // The other request still owns the run.+ expect(processGone(pid)).toBe(false);++ secondCaller.abort();+ expect(await second).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ expect(await cache.close()).toEqual({ ok: true, value: null });+ expect(processGone(pid)).toBe(true);+ expect(await entries(cacheRoot, "staging")).toEqual([]);+ expect(await entries(cacheRoot, "projects")).toEqual([]);+});++it("applies one deadline to the inventory and the export together", async () => {+ const { kuna, installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-timeout-",+ { project: "hang" },+ { environment: { REA_KUNA_PROJECT_TIMEOUT_MS: "800" } },+ );++ const result = await cache.build({+ installation,+ ...(await target("program")),+ });++ expect(result).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisTimeoutError", timeoutMs: 800 },+ });+ const [exported] = await callsOf(kuna, "decompile-project");+ expect(processGone(exported?.pid ?? 0)).toBe(true);+ expect(await entries(cacheRoot, "staging")).toEqual([]);++ await setFakeKunaBehavior(kuna, { inventory: "hang" });+ expect(+ await cache.build({ installation, ...(await target("other")) }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisTimeoutError" } });+});++it("reports a failed export with Kuna's diagnostics and retains nothing", async () => {+ const { installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-failure-",+ { project: "exit-failure" },+ );++ const result = await cache.build({+ installation,+ ...(await target("program")),+ });++ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ userMessage:+ "kuna decompile-project failed with exit code 1: error: not in recognized object file format",+ capturedOutput: { exit_code: 1 },+ },+ });+ expect(await entries(cacheRoot, "projects")).toEqual([]);+ expect(await entries(cacheRoot, "staging")).toEqual([]);+});++it.each([+ [+ "an inventory that is not Kuna's JSON document",+ { inventory: "not-json" },+ "inventory is not JSON",+ ],+ [+ "an export without Kuna's completed-file summary",+ { project: "silent" },+ "summary",+ ],+ [+ "an export whose headers disagree with Kuna's summary",+ { project: "miscounted" },+ "2 function headers but Kuna reported 3 functions",+ ],+] as const)("refuses %s", async (_case, behavior, reason) => {+ const { installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-refused-",+ behavior,+ );++ expect(+ await cache.build({ installation, ...(await target("program")) }),+ ).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ userMessage: expect.stringContaining(reason),+ },+ });+ expect(await entries(cacheRoot, "projects")).toEqual([]);+ expect(await entries(cacheRoot, "staging")).toEqual([]);+});++it("refuses to decompile a target that no longer matches its digest", async () => {+ const { kuna, installation, cache, target } =+ await fixture("rea-kuna-changed-");+ const input = await target("program");+ await appendFile(input.targetPath, "patched");++ expect(await cache.build({ installation, ...input })).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisArtifactChangedError", path: input.targetPath },+ });+ expect(await fakeKunaCalls(kuna)).toHaveLength(1);+});++it("removes its staging when the target disappears before the copy", async () => {+ const { installation, cacheRoot, cache, target } =+ await fixture("rea-kuna-vanished-");+ const input = await target("program");++ const result = await cache.build({+ installation,+ ...input,+ targetPath: `${input.targetPath}.gone`,+ });++ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ userMessage: expect.stringContaining("ENOENT"),+ },+ });+ expect(await entries(cacheRoot, "staging")).toEqual([]);+});++it("discards an entry whose files no longer match their manifest", async () => {+ const { installation, cacheRoot, cache, target } =+ await fixture("rea-kuna-tamper-");+ const input = await target("program");+ const built = await cache.build({ installation, ...input });+ if (!built.ok) throw built.error;+ await appendFile(join(built.value.directory, "program.c"), "// edited\n");++ expect(await newCache(installation).lookup(built.value.key)).toBeUndefined();+ expect(await entries(cacheRoot, "projects")).toEqual([]);+});++it("evicts least recently used entries above the cap, never a pinned one", async () => {+ const { installation, cacheRoot, target } = await fixture("rea-kuna-evict-", {+ asmPadding: 400 * 1024,+ });+ const cache = newCache(installation, 1024 * 1024);+ const build = async (name: string, ageSeconds: number) => {+ const result = await cache.build({ installation, ...(await target(name)) });+ if (!result.ok) throw result.error;+ const when = new Date(Date.now() - ageSeconds * 1000);+ await utimes(join(cacheRoot, "projects", result.value.key), when, when);+ return result.value.key;+ };++ const oldest = await build("oldest", 30);+ const pinned = await build("pinned", 40);+ const release = cache.pin(pinned);+ const newest = await build("newest", 0);++ // Three ~400 KiB entries exceed 1 MiB: the oldest unpinned entry goes.+ expect((await entries(cacheRoot, "projects")).sort()).toEqual(+ [pinned, newest].sort(),+ );+ expect(await cache.lookup(oldest)).toBeUndefined();++ release();+ await build("latest", 0);+ expect(await entries(cacheRoot, "projects")).not.toContain(pinned);+});++it("refuses an export larger than the whole cache may hold", async () => {+ const { installation, cacheRoot, target } = await fixture(+ "rea-kuna-capacity-",+ { asmPadding: 8 * 1024 },+ );++ const result = await newCache(installation, 4096).build({+ installation,+ ...(await target("program")),+ });++ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisResourceConstraintError",+ resource: "capacity",+ reportedLimits: { cache_max_bytes: 4096 },+ },+ });+ expect(await entries(cacheRoot, "projects")).toEqual([]);+});++it("keeps the first publication when another process exports the same key", async () => {+ const { kuna, installation, cacheRoot, target } = await fixture(+ "rea-kuna-race-",+ { delayMs: 300 },+ );+ const input = await target("program");++ // Two cache instances stand in for two REA processes sharing one root.+ const [first, second] = await Promise.all([+ newCache(installation).build({ installation, ...input }),+ newCache(installation).build({ installation, ...input }),+ ]);++ expect(await callsOf(kuna, "decompile-project")).toHaveLength(2);+ expect(first.ok && second.ok).toBe(true);+ if (first.ok && second.ok)+ expect(first.value.manifest).toEqual(second.value.manifest);+ expect(await entries(cacheRoot, "projects")).toEqual([+ keyOf(installation, input),+ ]);+ expect(await entries(cacheRoot, "staging")).toEqual([]);+});++it("reports each build phase to every waiting request", async () => {+ const { installation, cache, target } = await fixture("rea-kuna-phases-");+ const statuses: KunaExportStatus[] = [];++ const result = await cache.build({+ installation,+ ...(await target("program")),+ onStatus: (status) => statuses.push(status),+ });++ expect(result.ok).toBe(true);+ expect(statuses).toEqual([+ { phase: "inventory", inventoryFunctions: null },+ { phase: "decompiling", inventoryFunctions: 3 },+ { phase: "sealing", inventoryFunctions: 3 },+ ]);+});++it("sweeps retired entries but preserves staging with unresolved process ownership", async () => {+ const { installation, cacheRoot, cache, target } =+ await fixture("rea-kuna-sweep-");+ const abandoned = join(cacheRoot, "staging", "build-abandoned");+ const recent = join(cacheRoot, "staging", "build-recent");+ const evicted = join(cacheRoot, "trash", "evicted");+ for (const path of [abandoned, recent, evicted])+ await mkdir(path, { recursive: true });+ const twoDaysAgo = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000);+ await utimes(abandoned, twoDaysAgo, twoDaysAgo);++ expect(+ (await cache.build({ installation, ...(await target("program")) })).ok,+ ).toBe(true);++ expect(await entries(cacheRoot, "staging")).toEqual([+ "build-abandoned",+ "build-recent",+ ]);+ expect(await entries(cacheRoot, "trash")).toEqual([]);+});++it.each(["sweep", "close"] as const)(+ "keeps failed file cleanup owned until recovery through %s",+ async (recovery) => {+ const { installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-trash-cleanup-",+ );+ const retired = join(cacheRoot, "trash", "retired");+ await mkdir(retired, { recursive: true });+ await writeFile(join(retired, "evidence"), "retained export");+ await chmod(retired, 0o500);+ let built;+ let closed;+ try {+ built = await cache.build({ installation, ...(await target("program")) });+ closed = await cache.close();+ } finally {+ await chmod(retired, 0o700);+ }++ if (!built.ok) throw built.error;+ expect(closed).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true, cleanupResources: [retired] },+ });+ expect(await readFile(join(retired, "evidence"), "utf8")).toBe(+ "retained export",+ );+ if (recovery === "sweep") {+ const next = await cache.build({+ installation,+ ...(await target("other")),+ });+ if (!next.ok) throw next.error;+ }+ expect(await cache.close()).toEqual({ ok: true, value: null });+ expect(await entries(cacheRoot, "trash")).toEqual([]);+ },+);++it("keeps staging owned when a cancelled Kuna process cannot be proven stopped", async () => {+ const { kuna, installation, cacheRoot, target } = await fixture(+ "rea-kuna-retained-",+ { project: "hang" },+ );+ // Stop the process for real, but report that ownership could not be revalidated.+ const cache = new KunaProjectCache(cacheRoot, {+ maxBytes: 64 * 1024 ** 2,+ launcher: async (options) => {+ const spawned = await spawnOwnedProviderProcess(options);+ if (options.arguments[0] !== "decompile-project") return spawned;+ const workspace = options.cwd;+ if (workspace === undefined) throw new Error("Kuna workspace is missing");+ return {+ ...spawned,+ cleanup: async () => {+ await cleanupOwnedProcessGroup(spawned.ownership);+ // A full disk or lost directory write access can prevent a final+ // lifecycle marker. Cleanup must remain fail-closed across instances.+ await chmod(workspace, 0o500);+ return {+ cleaned: false,+ reason: "ownership could not be revalidated",+ };+ },+ };+ },+ });+ const caller = new AbortController();+ const build = cache.build({+ installation,+ ...(await target("program")),+ signal: caller.signal,+ });+ await expect.poll(() => callsOf(kuna, "decompile-project")).toHaveLength(1);++ caller.abort();+ expect(await build).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ const closed = await cache.close();+ const staged = await entries(cacheRoot, "staging");+ const retained = join(cacheRoot, "staging", staged[0] ?? "missing");+ // Restore access before assertions so the fixture can always remove it.+ await chmod(retained, 0o700);++ expect(closed).toMatchObject({+ ok: false,+ error: {+ cleanupIncomplete: true,+ diagnostics: { reason: "ownership could not be revalidated" },+ },+ });+ expect(staged).toHaveLength(1);+ if (!closed.ok) expect(closed.error.cleanupResources).toContain(retained);++ const twoDaysAgo = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000);+ await utimes(retained, twoDaysAgo, twoDaysAgo);+ await setFakeKunaBehavior(kuna, {});+ const other = newCache(installation);+ const built = await other.build({+ installation,+ ...(await target("other")),+ });+ if (!built.ok) throw built.error;+ expect(await entries(cacheRoot, "staging")).toEqual(staged);+ expect(await readFile(join(retained, "input", "program"), "utf8")).toBe(+ "program",+ );+ expect(await other.close()).toEqual({ ok: true, value: null });+ // The fake process really stopped, so the test can remove its files. File+ // absence still does not resolve the deliberately unproven process record.+ await rm(retained, { recursive: true });+ expect(await cache.close()).toMatchObject({+ ok: false,+ error: { diagnostics: { reason: "ownership could not be revalidated" } },+ });+});++it("rebuilds an entry another cache instance evicted after this one verified it", async () => {+ const { kuna, installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-evicted-elsewhere-",+ );+ const input = await target("program");+ const built = await cache.build({ installation, ...input });+ if (!built.ok) throw built.error;+ // Another process retires the entry the way #discard does.+ await mkdir(join(cacheRoot, "trash"), { recursive: true });+ await rename(+ join(cacheRoot, "projects", built.value.key),+ join(cacheRoot, "trash", "evicted"),+ );++ expect(await cache.lookup(built.value.key)).toBeUndefined();+ const rebuilt = await cache.build({ installation, ...input });++ expect(rebuilt.ok).toBe(true);+ expect(await callsOf(kuna, "decompile-project")).toHaveLength(2);+ expect(await entries(cacheRoot, "projects")).toEqual([built.value.key]);+});++it("reports an abandoned build's unproven cleanup even after a retry replaced it", async () => {+ const { kuna, installation, cacheRoot, target } = await fixture(+ "rea-kuna-replaced-",+ { project: "hang" },+ );+ let exports = 0;+ const cache = new KunaProjectCache(cacheRoot, {+ maxBytes: 64 * 1024 ** 2,+ launcher: async (options) => {+ const spawned = await spawnOwnedProviderProcess(options);+ if (options.arguments[0] !== "decompile-project" || ++exports > 1)+ return spawned;+ // The first export stops slowly and cannot prove its group gone.+ return {+ ...spawned,+ cleanup: async () => {+ await new Promise((resolve) => setTimeout(resolve, 500));+ await cleanupOwnedProcessGroup(spawned.ownership);+ return { cleaned: false, reason: "first export unverified" };+ },+ };+ },+ });+ const input = await target("program");+ const first = new AbortController();+ const firstBuild = cache.build({+ installation,+ ...input,+ signal: first.signal,+ });+ await expect.poll(() => callsOf(kuna, "decompile-project")).toHaveLength(1);+ first.abort();+ await firstBuild;++ // A retry for the same key starts while the first is still stopping.+ const second = new AbortController();+ const secondBuild = cache.build({+ installation,+ ...input,+ signal: second.signal,+ });+ await expect.poll(() => callsOf(kuna, "decompile-project")).toHaveLength(2);+ second.abort();+ await secondBuild;++ expect(await cache.close()).toMatchObject({+ ok: false,+ error: { diagnostics: { reason: "first export unverified" } },+ });+});++it("removes its staging when publication itself fails", async () => {+ const { installation, cacheRoot, cache, target } = await fixture(+ "rea-kuna-publish-failure-",+ { project: "block-manifest" },+ );++ const result = await cache.build({+ installation,+ ...(await target("program")),+ });++ expect(result).toMatchObject({+ ok: false,+ error: { _tag: "ProviderAdapterError" },+ });+ expect(await entries(cacheRoot, "staging")).toEqual([]);+ expect(await entries(cacheRoot, "projects")).toEqual([]);+});diff --git a/tests/boundary/providers/kuna/kunaProjectConcurrency.test.ts b/tests/boundary/providers/kuna/kunaProjectConcurrency.test.tsnew file mode 100644index 000000000..ccb3c50c3--- /dev/null+++ b/tests/boundary/providers/kuna/kunaProjectConcurrency.test.ts@@ -0,0 +1,252 @@+import { createHash } from "node:crypto";+import { appendFileSync } from "node:fs";+import { readFile, readdir, writeFile } from "node:fs/promises";+import { join } from "node:path";++import { afterEach, expect, it as test, onTestFinished, vi } from "vitest";++import { inspectKunaInstallation } from "../../../../src/kuna/KunaInstallation.js";+import { KunaProjectCache } from "../../../../src/kuna/KunaProjectCache.js";+import type { KunaExportStatus } from "../../../../src/kuna/KunaProjectExport.js";+import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import { fakeKunaCalls, writeFakeKuna } from "./fakeKuna.js";++// Reproduce concurrent eviction's shared directory snapshot while retaining+// real exports, publication, hashing and file removal underneath it.+const listing = vi.hoisted(() => ({+ directory: "",+ names: [] as string[],+ gate: undefined as Promise<void> | undefined,+ arrived: 0,+ touchPath: "",+ touchGate: undefined as Promise<void> | undefined,+ touched: false,+}));++vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...actual,+ readdir: async (...args: Parameters<typeof actual.readdir>) => {+ if (String(args[0]) === listing.directory && listing.gate !== undefined) {+ listing.arrived += 1;+ await listing.gate;+ return listing.names;+ }+ return actual.readdir(...args);+ },+ utimes: async (...args: Parameters<typeof actual.utimes>) => {+ await actual.utimes(...args);+ if (+ String(args[0]) === listing.touchPath &&+ listing.touchGate !== undefined+ ) {+ listing.touched = true;+ await listing.touchGate;+ }+ },+ };+});++afterEach(() => {+ listing.directory = "";+ listing.gate = undefined;+ listing.names = [];+ listing.arrived = 0;+ listing.touchPath = "";+ listing.touchGate = undefined;+ listing.touched = false;+});++const it = test.skipIf(process.platform === "win32");++const barrier = () => {+ let release = () => {};+ const promise = new Promise<void>((resolve) => {+ release = resolve;+ });+ return { promise, release };+};++const fixture = async (maxBytes = 64 * 1024 ** 2) => {+ const root = await createTestTempDirectory("rea-kuna-concurrency-");+ const kuna = await writeFakeKuna(root, {+ delayMs: 300,+ asmPadding: 400 * 1024,+ });+ const inspected = await inspectKunaInstallation({+ REA_KUNA_COMMAND: kuna,+ REA_KUNA_CACHE_DIR: join(root, "cache"),+ });+ if (!inspected.ok) throw new Error(inspected.error.reason);+ const installation = inspected.value;+ const cache = new KunaProjectCache(installation.configuration.cacheRoot, {+ maxBytes,+ });+ const request = async (name: string) => {+ const targetPath = join(root, name);+ await writeFile(targetPath, name);+ return {+ installation,+ targetPath,+ targetSha256: createHash("sha256").update(name).digest("hex"),+ };+ };+ return {+ kuna,+ cache,+ request,+ cacheRoot: installation.configuration.cacheRoot,+ };+};++it.each([true, false])(+ "preserves concurrent results and reclaims capacity (pin: %s)",+ async (pin) => {+ const { cache, request, cacheRoot } = await fixture(600 * 1024);+ const actual =+ await vi.importActual<typeof import("node:fs/promises")>(+ "node:fs/promises",+ );+ let releaseListing = () => {};+ const gate = new Promise<void>((resolve) => {+ releaseListing = resolve;+ });+ listing.directory = join(cacheRoot, "projects");+ listing.gate = gate;+ const releases: (() => void)[] = [];+ const inputs = await Promise.all([request("first"), request("second")]);+ const builds = inputs.map(async (input) => {+ const result = await cache.build(input);+ if (!result.ok) throw result.error;+ if (pin) releases.push(cache.pin(result.value.key));+ return result.value;+ });+ onTestFinished(async () => {+ releaseListing();+ await Promise.allSettled(builds);+ for (const release of releases) release();+ const closed = await cache.close();+ if (!closed.ok) throw closed.error;+ });+ await expect+ .poll(() => actual.readdir(listing.directory).catch(() => []))+ .toHaveLength(2);+ listing.names = await actual.readdir(listing.directory);+ releaseListing();+ const projects = await Promise.all(builds);+ if (!pin) {+ expect(await cache.close()).toEqual({ ok: true, value: null });+ expect(await actual.readdir(listing.directory)).toHaveLength(1);+ return;+ }+ for (const project of projects) {+ expect(+ await readFile(+ join(project.directory, project.manifest.files.c.path),+ "utf8",+ ),+ ).toContain("// Function: main @ 0x1000");+ }+ },+);++it.each(["decompiling", "sealing"] as const)(+ "rejects an executable changed during %s",+ async (phase) => {+ const { kuna, cache, request, cacheRoot } = await fixture();+ const input = await request("program");+ const result = await cache.build({+ ...input,+ onStatus: (status) => {+ if (status.phase === phase)+ appendFileSync(kuna, "\n// installation replaced\n");+ },+ });+ expect(result).toMatchObject({+ ok: false,+ error: {+ diagnostics: {+ expected_sha256: input.installation.sha256,+ observed_sha256: expect.any(String),+ },+ },+ });+ expect(await readdir(join(cacheRoot, "projects"))).toEqual([]);+ expect(await cache.close()).toEqual({ ok: true, value: null });+ },+);++it("protects a cache request that arrives after an eviction snapshot starts", async () => {+ const { cache, cacheRoot, request } = await fixture(600 * 1024);+ const actual =+ await vi.importActual<typeof import("node:fs/promises")>(+ "node:fs/promises",+ );+ const firstInput = await request("first");+ const first = await cache.build(firstInput);+ if (!first.ok) throw first.error;+ const snapshot = barrier();+ const touch = barrier();+ listing.directory = join(cacheRoot, "projects");+ listing.gate = snapshot.promise;+ listing.touchPath = join(listing.directory, first.value.key);+ listing.touchGate = touch.promise;+ const releases: (() => void)[] = [];+ const pinResult = async (pending: ReturnType<KunaProjectCache["build"]>) => {+ const result = await pending;+ if (!result.ok) throw result.error;+ releases.push(cache.pin(result.value.key));+ return result.value;+ };+ const second = pinResult(cache.build(await request("second")));+ let warm: ReturnType<typeof pinResult> | undefined;+ onTestFinished(async () => {+ snapshot.release();+ touch.release();+ await Promise.allSettled(warm === undefined ? [second] : [second, warm]);+ for (const release of releases) release();+ const closed = await cache.close();+ if (!closed.ok) throw closed.error;+ });+ await expect.poll(() => listing.arrived).toBe(1);+ warm = pinResult(cache.build(firstInput));+ await expect.poll(() => listing.touched).toBe(true);+ listing.names = await actual.readdir(listing.directory);+ snapshot.release();+ await second;+ touch.release();+ const reused = await warm;+ expect(+ await readFile(+ join(reused.directory, reused.manifest.files.c.path),+ "utf8",+ ),+ ).toContain("// Function: main @ 0x1000");+});++it("keeps a shared progress callback registered for the remaining waiter", async () => {+ const { kuna, cache, request } = await fixture();+ const input = await request("program");+ const controller = new AbortController();+ const statuses: KunaExportStatus[] = [];+ const onStatus = (status: KunaExportStatus) => {+ statuses.push(status);+ if (status.phase === "decompiling") controller.abort();+ };+ const first = cache.build({ ...input, signal: controller.signal, onStatus });+ const second = cache.build({ ...input, onStatus });+ expect(await first).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ const result = await second;+ if (!result.ok) throw result.error;+ expect(statuses.map(({ phase }) => phase)).toContain("sealing");+ expect(+ (await fakeKunaCalls(kuna)).filter(+ ({ argv }) => argv[0] === "decompile-project",+ ),+ ).toHaveLength(1);+ expect(await cache.close()).toEqual({ ok: true, value: null });+});diff --git a/tests/boundary/providers/kuna/kunaProjectFiles.test.ts b/tests/boundary/providers/kuna/kunaProjectFiles.test.tsnew file mode 100644index 000000000..b39dbb574--- /dev/null+++ b/tests/boundary/providers/kuna/kunaProjectFiles.test.ts@@ -0,0 +1,164 @@+import { expect, it } from "vitest";++import {+ parseKunaExportSummary,+ parseKunaInventory,+ scanKunaProjectSource,+} from "../../../../src/kuna/KunaProjectFiles.js";++const SOURCE = [+ '#include "a.out.h"',+ "",+ "// Function: main @ 0x1000",+ "int main(void)",+ "{",+ ' return puts("// Function: not a header");',+ "}",+ "",+ "// Function: operator new(unsigned long) @ 0x1040",+ "void *operator new(unsigned long a0) { return malloc(a0); }",+ "",+ "// Function: sub_1080 @ 0x1080 (error: Flow exceeded maximum allowable instructions)",+ "",+ "",+].join("\n");++/** Feed the text in fixed-size pieces so headers straddle chunk boundaries. */+async function* chunked(text: string, size: number): AsyncGenerator<Buffer> {+ const bytes = Buffer.from(text);+ for (let offset = 0; offset < bytes.length; offset += size)+ yield bytes.subarray(offset, offset + size);+}++it("splits Kuna's .c into function blocks at any chunk size", async () => {+ // SOURCE is ASCII, so string offsets are byte offsets.+ const starts = [+ SOURCE.indexOf("// Function: main"),+ SOURCE.indexOf("// Function: operator new"),+ SOURCE.indexOf("// Function: sub_1080"),+ SOURCE.length,+ ];+ const span = (index: number) => ({+ cOffset: starts[index] ?? -1,+ cLength: (starts[index + 1] ?? -1) - (starts[index] ?? -1),+ });+ const expected = [+ { name: "main", address: "0x1000", ...span(0), error: null },+ {+ name: "operator new(unsigned long)",+ address: "0x1040",+ ...span(1),+ error: null,+ },+ {+ name: "sub_1080",+ address: "0x1080",+ ...span(2),+ error: "Flow exceeded maximum allowable instructions",+ },+ ];+ expect(SOURCE.slice(starts[0], starts[1])).toBe(+ '// Function: main @ 0x1000\nint main(void)\n{\n return puts("// Function: not a header");\n}\n\n',+ );+ for (const size of [1, 7, 64, 4096])+ expect(+ await scanKunaProjectSource(chunked(SOURCE, size), {+ decompiled: 2,+ failed: 1,+ }),+ ).toEqual({ ok: true, value: expected });+ const block = Buffer.from(SOURCE)+ .subarray(expected[2]?.cOffset, SOURCE.length)+ .toString();+ expect(block.startsWith("// Function: sub_1080 @ 0x1080 (error:")).toBe(+ true,+ );+});++it.each([+ [+ "a header count that disagrees with Kuna's summary",+ SOURCE,+ { decompiled: 3, failed: 1 },+ "3 function headers but Kuna reported 4",+ ],+ [+ "a failure count that disagrees with Kuna's summary",+ SOURCE,+ { decompiled: 3, failed: 0 },+ "marks 1 failed functions but Kuna reported 0",+ ],+ [+ "a malformed header",+ "// Function: main at 0x1000\n",+ { decompiled: 1, failed: 0 },+ "unrecognized function header at byte 0",+ ],+ [+ "a repeated address",+ "// Function: a @ 0x10\n\n// Function: b @ 0x10\n\n",+ { decompiled: 2, failed: 0 },+ "repeats address 0x10",+ ],+ [+ "an overlong header line",+ `// Function: ${"x".repeat(70_000)} @ 0x10\n`,+ { decompiled: 1, failed: 0 },+ "too long",+ ],+] as const)("refuses %s", async (_case, source, summary, reason) => {+ expect(await scanKunaProjectSource(chunked(source, 4096), summary)).toEqual({+ ok: false,+ error: expect.stringContaining(reason),+ });+});++it("reads Kuna's completed-export summary from its stdout", () => {+ expect(+ parseKunaExportSummary(+ "wrote ./a.out.kuna: a.out.c (325163 bytes), a.out.h (21366 bytes); functions: 172 ok, 3 failed\n",+ ),+ ).toEqual({ decompiled: 172, failed: 3 });+ expect(parseKunaExportSummary("wrote ./a.out.kuna\n")).toBeUndefined();+});++it("reads the callable inventory, ignoring fields a later release adds", () => {+ expect(+ parseKunaInventory(+ JSON.stringify({+ binary: "a.out",+ count: 1,+ total: 1,+ error: null,+ functions: [+ {+ name: "_inflate",+ address: 4294995696,+ address_hex: "0x100006ef0",+ aliases: ["inflate"],+ object_location: null,+ size: 252,+ interior: false,+ },+ ],+ }),+ ),+ ).toEqual({+ ok: true,+ value: [+ {+ name: "_inflate",+ address: "0x100006ef0",+ aliases: ["inflate"],+ size: 252,+ },+ ],+ });+ expect(parseKunaInventory("functions: 1")).toEqual({+ ok: false,+ error: "the function inventory is not JSON",+ });+ expect(+ parseKunaInventory(JSON.stringify({ functions: [{ name: "x" }] })),+ ).toMatchObject({ ok: false });+});