lagora-cli 1.1.0

package/dist/scripts/verification-3QCY66QW.js

@@ -0,0 +1,772 @@
+import {
+  loweringWorkerEnv
+} from "./chunk-RIR5KGHC.js";
+import "./chunk-UQ6I6VTY.js";
+import {
+  getArtifactTextPath,
+  getIssue,
+  recordVerificationResult,
+  storedGeneratedArtifactFilename,
+  updateVerificationRunResult
+} from "./chunk-NBJMYAOA.js";
+import "./chunk-QJPQHKIO.js";
+
+// lib/verification.ts
+import { fileURLToPath as packageFilePath } from "node:url";
+import { execFile, spawn } from "child_process";
+import { createHash } from "crypto";
+import { access as access2, mkdtemp, readFile as readFile2, rm } from "fs/promises";
+import { tmpdir } from "os";
+import path2 from "path";
+import { promisify } from "util";
+
+// lib/verification-generated-artifacts.ts
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+// lib/artifact-content.ts
+var TEXT_PREVIEW_MAX_BYTES = 512 * 1024;
+var BINARY_HEX_PREVIEW_BYTES = 4 * 1024;
+
+// lib/verification-generated-artifacts.ts
+var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([".mlir", ".ll", ".s", ".asm", ".json"]);
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([".bin", ".elf", ".o", ".bc"]);
+var EXCLUDED_EXTENSIONS = /* @__PURE__ */ new Set([".log", ".tmp", ".pyc", ".pyo"]);
+async function listGeneratedArtifacts(root) {
+  const entries = [];
+  async function visit(directory) {
+    let children;
+    try {
+      children = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (!(error instanceof Error)) throw error;
+      return;
+    }
+    for (const child of children) {
+      const childPath = path.join(directory, child.name);
+      const relativePath = path.relative(root, childPath);
+      if (child.isDirectory()) {
+        if (isIgnoredGeneratedPath(relativePath)) continue;
+        await visit(childPath);
+      } else if (isMeaningfulGeneratedArtifact(relativePath)) {
+        entries.push(relativePath);
+      }
+    }
+  }
+  await visit(root);
+  return entries.sort(compareGeneratedArtifacts);
+}
+async function collectGeneratedArtifactFiles(root) {
+  const files = [];
+  for (const relativePath of await listGeneratedArtifacts(root)) {
+    const bytes = await readFile(path.join(root, relativePath));
+    files.push({
+      filename: storedGeneratedArtifactFilename(relativePath),
+      contentType: contentTypeForGeneratedArtifact(relativePath),
+      contentBase64: bytes.toString("base64")
+    });
+  }
+  return files;
+}
+function isMeaningfulGeneratedArtifact(relativePath) {
+  if (isIgnoredGeneratedPath(relativePath)) return false;
+  const extension = path.extname(relativePath).toLowerCase();
+  if (EXCLUDED_EXTENSIONS.has(extension)) return false;
+  return TEXT_EXTENSIONS.has(extension) || BINARY_EXTENSIONS.has(extension);
+}
+function isIgnoredGeneratedPath(relativePath) {
+  const parts = relativePath.split(path.sep);
+  return parts.some((part) => part === "__pycache__" || part.startsWith(".") || part.startsWith("tmp") || part.endsWith(".tmp"));
+}
+function contentTypeForGeneratedArtifact(relativePath) {
+  const extension = path.extname(relativePath).toLowerCase();
+  return TEXT_EXTENSIONS.has(extension) ? "text/plain" : "application/octet-stream";
+}
+function compareGeneratedArtifacts(left, right) {
+  const rankDelta = stageRank(left) - stageRank(right);
+  return rankDelta !== 0 ? rankDelta : left.localeCompare(right);
+}
+function stageRank(relativePath) {
+  const stage = relativePath.split(/[\\/]/)[0]?.toLowerCase();
+  if (stage === "mlir") return 0;
+  if (stage === "core_ir") return 1;
+  if (stage === "backend_ir") return 2;
+  if (stage === "asm") return 3;
+  if (stage === "binary") return 4;
+  return 5;
+}
+
+// lib/verification-sdk-preflight.ts
+import { access } from "node:fs/promises";
+async function preflightLoweringRuntime(input) {
+  const missing = [];
+  if (input.runtimeStatus !== "ready") {
+    missing.push(`SDK runtime is not ready: ${input.runtimeStatus}${input.runtimeMessage ? ` (${input.runtimeMessage})` : ""}`);
+  }
+  await collectMissingPath(missing, "SDK runtime root", input.runtimeRoot);
+  await collectMissingPath(missing, "Legato Python", input.python);
+  await collectMissingPath(missing, "lowering runner", input.runnerPath);
+  if (missing.length === 0) return void 0;
+  return {
+    status: "failed",
+    exitCode: 2,
+    stdout: "[LEGATO_WORKER] preflight=failed\n",
+    stderr: [
+      "Backend lowering preflight failed before running the compiler.",
+      "The server must use a prepared HyperAccel SDK runtime; lowering workers do not install packages, clone, or fetch repositories.",
+      ...missing.map((item) => `- ${item}`),
+      "Prepare the SDK from Settings > SDK > Prepare / update runtime, or wait for startup preparation to finish."
+    ].join("\n"),
+    failedStage: "PREFLIGHT",
+    skippedEvidence: missing
+  };
+}
+async function collectMissingPath(missing, label, candidate) {
+  try {
+    await access(candidate);
+  } catch {
+    missing.push(`${label}: ${candidate}`);
+  }
+}
+
+// lib/verification.ts
+var execFileAsync = promisify(execFile);
+var DEFAULT_LOWERING_TIMEOUT_MS = 12e4;
+var DEFAULT_FSIM_TIMEOUT_MS = 144e5;
+async function runIssueVerification(input) {
+  const mode = input.mode ?? "plan";
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const record = await getIssue(input.issueId);
+  if (!record) throw new Error(`Issue not found: ${input.issueId}`);
+  if ((input.kind === "lowering" || input.kind === "fsim") && mode === "real") {
+    await ensureLoweringRuntimePrepared(input.sdkRuntime);
+  }
+  const kernelArtifact = input.sourceArtifactId ? record.artifacts.find((artifact) => artifact.id === input.sourceArtifactId) : record.artifacts.find((artifact) => artifact.id === record.bundle.kernelArtifactId);
+  if (input.sourceArtifactId && !kernelArtifact) throw new Error(`Source artifact not found: ${input.sourceArtifactId}`);
+  const coreIrArtifact = findCoreIrArtifact(record.artifacts);
+  const plan = input.kind === "lowering" ? await loweringPlan(kernelArtifact, coreIrArtifact, input.sdkRuntime) : await fsimPlan(kernelArtifact, input.sdkRuntime);
+  const updateLiveRun = input.runId ? async (result2) => {
+    await updateVerificationRunResult({
+      issueId: input.issueId,
+      runId: input.runId ?? "",
+      kind: input.kind,
+      sourceArtifactId: input.sourceArtifactId,
+      actorUserId: input.actorUserId,
+      status: result2.status,
+      exitCode: result2.exitCode,
+      toolVersion: result2.toolVersion,
+      failedStage: result2.failedStage,
+      completedStage: result2.completedStage,
+      sdkRepoUrl: result2.sdkRepoUrl,
+      sdkBranch: result2.sdkBranch,
+      sdkCommitSha: result2.sdkCommitSha,
+      sdkPreparedRoot: result2.sdkPreparedRoot,
+      startedAt,
+      completedAt: result2.status === "running" ? startedAt : (/* @__PURE__ */ new Date()).toISOString(),
+      logText: buildLog({
+        issueId: input.issueId,
+        kind: input.kind,
+        mode,
+        startedAt,
+        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        plan,
+        result: result2,
+        kernelArtifact,
+        coreIrArtifact
+      })
+    });
+  } : void 0;
+  const result = await executePlan(input.kind, mode, plan, kernelArtifact, coreIrArtifact, input.sdkRuntime, updateLiveRun);
+  const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const fingerprint = input.kind === "lowering" ? buildVerificationFingerprint(result, kernelArtifact, completedAt) : void 0;
+  const logText = buildLog({
+    issueId: input.issueId,
+    kind: input.kind,
+    sourceArtifactId: input.sourceArtifactId,
+    mode,
+    startedAt,
+    completedAt,
+    plan,
+    result,
+    kernelArtifact,
+    coreIrArtifact
+  });
+  const recordInput = {
+    issueId: input.issueId,
+    kind: input.kind,
+    actorUserId: input.actorUserId,
+    status: result.status,
+    exitCode: result.exitCode,
+    toolVersion: result.toolVersion,
+    failedStage: result.failedStage,
+    completedStage: result.completedStage,
+    generatedArtifacts: result.generatedArtifacts,
+    generatedArtifactFiles: result.generatedArtifactFiles,
+    sdkRepoUrl: result.sdkRepoUrl,
+    sdkBranch: result.sdkBranch,
+    sdkCommitSha: result.sdkCommitSha,
+    sdkPreparedRoot: result.sdkPreparedRoot,
+    fingerprint,
+    startedAt,
+    completedAt,
+    logText,
+    commentBody: verificationSummary(input.kind, result, plan.reason)
+  };
+  return input.runId ? updateVerificationRunResult({ ...recordInput, runId: input.runId }) : recordVerificationResult(recordInput);
+}
+async function ensureLoweringRuntimePrepared(sdkRuntime) {
+  const { prepareSdkRuntime, readSdkRuntimeStatus } = await import("./sdk-runtime-JE6H2PB2.js");
+  if (sdkRuntime?.preparedRoot) {
+    const status = await readSdkRuntimeStatus(sdkRuntime);
+    if (status.status === "ready" && await pathExists(status.pythonPath)) return;
+  }
+  await prepareSdkRuntime(sdkRuntime);
+}
+async function maybeRunAutoLowering(issueId) {
+  try {
+    await runIssueVerification({ issueId, kind: "lowering", mode: "real" });
+  } catch (error) {
+    console.error("Auto lowering failed", error);
+  }
+}
+function findCoreIrArtifact(artifacts) {
+  return artifacts.find((artifact) => artifact.filename.endsWith(".mlir"));
+}
+async function loweringPlan(kernelArtifact, coreIrArtifact, sdkRuntime) {
+  if (kernelArtifact?.filename.endsWith(".py")) {
+    const { readSdkRuntimeSettings, readSdkRuntimeStatus } = await import("./sdk-runtime-JE6H2PB2.js");
+    const runtime = await readSdkRuntimeSettings(sdkRuntime);
+    const status = await readSdkRuntimeStatus(sdkRuntime);
+    const activeRuntime = sdkRuntimeExecutionView(runtime, status);
+    return {
+      command: activeRuntime.pythonPath,
+      args: ["scripts/legato-lowering-runner.py", "--kernel", kernelArtifact.filename, "--stages", process.env.AGORA_LOWERING_STAGES ?? "MLIR,CORE_IR,BACKEND_IR,ASM,BINARY"],
+      cwd: activeRuntime.preparedRoot,
+      reason: "Uploaded Python kernel will be imported and lowered stage-by-stage using Legato annotations."
+    };
+  }
+  const legatoOpt = await findExecutable(process.env.LEGATO_OPT, "legato-opt");
+  const coreIrPath = coreIrArtifact ? getArtifactTextPath(coreIrArtifact) : void 0;
+  return {
+    command: legatoOpt ?? "legato-opt",
+    args: ["--legato-bertha-convert-core-to-high", coreIrPath ?? "<core_ir.mlir>"],
+    cwd: process.cwd(),
+    reason: legatoOpt && coreIrPath ? "Legato lowering command is available for CORE_IR input." : `Skipped until ${legatoOpt ? "CORE_IR artifact" : "LEGATO_OPT or legato-opt"} is available. Kernel artifact: ${kernelArtifact?.filename ?? "missing"}.`
+  };
+}
+async function fsimPlan(kernelArtifact, sdkRuntime) {
+  const { readSdkRuntimeSettings, readSdkRuntimeStatus } = await import("./sdk-runtime-JE6H2PB2.js");
+  const runtime = await readSdkRuntimeSettings(sdkRuntime);
+  const status = await readSdkRuntimeStatus(sdkRuntime);
+  const activeRuntime = sdkRuntimeExecutionView(runtime, status);
+  if (kernelArtifact?.filename.endsWith(".py")) {
+    return {
+      command: activeRuntime.pythonPath,
+      args: ["scripts/legato-fsim-runner.py", "--kernel", kernelArtifact.filename],
+      cwd: activeRuntime.preparedRoot,
+      reason: "Uploaded Python launcher will compile BINARY and launch on HART fSIM through Legato session."
+    };
+  }
+  return {
+    command: activeRuntime.pythonPath,
+    args: ["-m", "pytest", "tests/simulator_compiler_integration/test_assembly_inst.py", "--use-verf", "-s"],
+    cwd: activeRuntime.preparedRoot,
+    reason: `No uploaded Python launcher was available; using the legacy pytest fSIM verification command. Kernel artifact: ${kernelArtifact?.filename ?? "missing"}.`
+  };
+}
+async function executePlan(kind, mode, plan, kernelArtifact, coreIrArtifact, sdkRuntime, updateLiveRun) {
+  if (mode === "plan") {
+    return {
+      status: "skipped",
+      stdout: "",
+      stderr: "",
+      skippedEvidence: ["--mode plan selected", "No heavyweight Legato/fSIM command was run."]
+    };
+  }
+  if (kind === "fsim" && kernelArtifact?.filename.endsWith(".py")) {
+    return executePythonFsim(kernelArtifact, sdkRuntime, updateLiveRun);
+  }
+  if (kind === "fsim") {
+    return executeLegacyFsim(plan, sdkRuntime);
+  }
+  if (kernelArtifact?.filename.endsWith(".py")) {
+    return executePythonLowering(kernelArtifact, sdkRuntime, updateLiveRun);
+  }
+  const executable = await findExecutable(process.env.LEGATO_OPT, "legato-opt");
+  if (!executable || !coreIrArtifact) {
+    return {
+      status: "skipped",
+      stdout: "",
+      stderr: "",
+      skippedEvidence: [
+        executable ? "legato-opt found" : "LEGATO_OPT/legato-opt not found or not executable",
+        coreIrArtifact ? "CORE_IR artifact found" : "No .mlir CORE_IR artifact is attached to the issue"
+      ]
+    };
+  }
+  try {
+    const version = await commandVersion(executable);
+    const output = await execFileAsync(executable, plan.args.slice(0, -1).concat(getArtifactTextPath(coreIrArtifact)), {
+      cwd: process.cwd(),
+      timeout: 3e4,
+      maxBuffer: 1024 * 1024
+    });
+    return { status: "success", exitCode: 0, stdout: output.stdout, stderr: output.stderr, toolVersion: version };
+  } catch (error) {
+    const failure = error;
+    return {
+      status: "failed",
+      exitCode: typeof failure.code === "number" ? failure.code : 1,
+      stdout: failure.stdout ?? "",
+      stderr: failure.stderr ?? failure.message ?? "unknown command failure",
+      toolVersion: await commandVersion(executable)
+    };
+  }
+}
+async function executePythonFsim(kernelArtifact, sdkRuntime, updateLiveRun) {
+  const { readSdkRuntimeSettings, readSdkRuntimeStatus } = await import("./sdk-runtime-JE6H2PB2.js");
+  const runtime = await readSdkRuntimeSettings(sdkRuntime);
+  const status = await readSdkRuntimeStatus(sdkRuntime);
+  const activeRuntime = sdkRuntimeExecutionView(runtime, status);
+  const runtimeMetadata = sdkRuntimeMetadata(activeRuntime, status);
+  const sdkRoot = path2.resolve(activeRuntime.preparedRoot);
+  const runnerPath = path2.join(
+    /*turbopackIgnore: true*/
+    packageFilePath(new URL(".", import.meta.url)),
+    "legato-fsim-runner.py"
+  );
+  const python = activeRuntime.pythonPath;
+  const preflightFailure = await preflightLoweringRuntime({
+    runtimeRoot: sdkRoot,
+    python,
+    runnerPath,
+    runtimeStatus: status.status,
+    runtimeMessage: status.message
+  });
+  if (preflightFailure) return { ...preflightFailure, failedStage: "FSIM", ...runtimeMetadata };
+  const outputRoot = await mkdtemp(path2.join(tmpdir(), "agora-legato-fsim-"));
+  const kernelPath = getArtifactTextPath(kernelArtifact);
+  const timeoutMs = readPositiveInt(process.env.AGORA_FSIM_TIMEOUT_MS ?? process.env.AGORA_LOWERING_TIMEOUT_MS, DEFAULT_FSIM_TIMEOUT_MS);
+  const env = loweringWorkerEnv(activeRuntime);
+  try {
+    const output = await spawnLoweringProcess(python, [
+      runnerPath,
+      "--kernel",
+      kernelPath,
+      "--output-root",
+      outputRoot
+    ], {
+      cwd: sdkRoot,
+      env,
+      timeoutMs,
+      updateLiveRun: updateLiveRun ? async (stdout, stderr) => {
+        await updateLiveRun({
+          status: "running",
+          stdout: sanitizeWorkerOutput(stdout),
+          stderr: sanitizeWorkerOutput(stderr),
+          completedStage: parseCompletedStage(stdout),
+          failedStage: parseFailedStage(`${stdout}
+${stderr}`),
+          ...runtimeMetadata
+        });
+      } : void 0
+    });
+    return {
+      status: "success",
+      exitCode: 0,
+      stdout: sanitizeWorkerOutput(output.stdout),
+      stderr: sanitizeWorkerOutput(output.stderr),
+      completedStage: parseCompletedStage(output.stdout) ?? "FSIM",
+      generatedArtifacts: await listGeneratedArtifacts(outputRoot),
+      generatedArtifactFiles: await collectGeneratedArtifactFiles(outputRoot),
+      ...runtimeMetadata
+    };
+  } catch (error) {
+    const failure = error;
+    const stdout = sanitizeWorkerOutput(failure.stdout ?? "");
+    const timeoutNote = failure.killed || failure.signal === "SIGTERM" ? `fSIM worker timed out after ${timeoutMs}ms` : "";
+    const stderr = sanitizeWorkerOutput([failure.stderr, timeoutNote, failure.message ?? "unknown fSIM failure"].filter(Boolean).join("\n"));
+    return {
+      status: "failed",
+      exitCode: typeof failure.code === "number" ? failure.code : 1,
+      stdout,
+      stderr,
+      failedStage: parseFailedStage(`${stdout}
+${stderr}`) ?? "FSIM",
+      completedStage: parseCompletedStage(stdout),
+      generatedArtifacts: await listGeneratedArtifacts(outputRoot),
+      generatedArtifactFiles: await collectGeneratedArtifactFiles(outputRoot),
+      ...runtimeMetadata
+    };
+  } finally {
+    await rm(outputRoot, { recursive: true, force: true });
+  }
+}
+async function executeLegacyFsim(plan, sdkRuntime) {
+  const { readSdkRuntimeSettings, readSdkRuntimeStatus } = await import("./sdk-runtime-JE6H2PB2.js");
+  const runtime = await readSdkRuntimeSettings(sdkRuntime);
+  const status = await readSdkRuntimeStatus(sdkRuntime);
+  const activeRuntime = sdkRuntimeExecutionView(runtime, status);
+  const runtimeMetadata = sdkRuntimeMetadata(activeRuntime, status);
+  const timeoutMs = readPositiveInt(process.env.AGORA_FSIM_TIMEOUT_MS ?? process.env.AGORA_LOWERING_TIMEOUT_MS, DEFAULT_FSIM_TIMEOUT_MS);
+  try {
+    const output = await execFileAsync(plan.command, plan.args, {
+      cwd: plan.cwd,
+      env: loweringWorkerEnv(activeRuntime),
+      timeout: timeoutMs,
+      maxBuffer: 2 * 1024 * 1024
+    });
+    return {
+      status: "success",
+      exitCode: 0,
+      stdout: sanitizeWorkerOutput(output.stdout),
+      stderr: sanitizeWorkerOutput(output.stderr),
+      completedStage: "FSIM",
+      ...runtimeMetadata
+    };
+  } catch (error) {
+    const failure = error;
+    const timeoutNote = failure.killed || failure.signal === "SIGTERM" ? `legacy fSIM command timed out after ${timeoutMs}ms` : "";
+    return {
+      status: "failed",
+      exitCode: typeof failure.code === "number" ? failure.code : 1,
+      stdout: sanitizeWorkerOutput(failure.stdout ?? ""),
+      stderr: sanitizeWorkerOutput([failure.stderr, timeoutNote, failure.message ?? "unknown legacy fSIM failure"].filter(Boolean).join("\n")),
+      failedStage: "FSIM",
+      ...runtimeMetadata
+    };
+  }
+}
+async function executePythonLowering(kernelArtifact, sdkRuntime, updateLiveRun) {
+  const { readSdkRuntimeSettings, readSdkRuntimeStatus } = await import("./sdk-runtime-JE6H2PB2.js");
+  const runtime = await readSdkRuntimeSettings(sdkRuntime);
+  const status = await readSdkRuntimeStatus(sdkRuntime);
+  const activeRuntime = sdkRuntimeExecutionView(runtime, status);
+  const runtimeMetadata = sdkRuntimeMetadata(activeRuntime, status);
+  const sdkRoot = path2.resolve(activeRuntime.preparedRoot);
+  const runnerPath = path2.join(
+    /*turbopackIgnore: true*/
+    packageFilePath(new URL(".", import.meta.url)),
+    "legato-lowering-runner.py"
+  );
+  const python = activeRuntime.pythonPath;
+  const preflightFailure = await preflightLoweringRuntime({
+    runtimeRoot: sdkRoot,
+    python,
+    runnerPath,
+    runtimeStatus: status.status,
+    runtimeMessage: status.message
+  });
+  if (preflightFailure) return { ...preflightFailure, ...runtimeMetadata };
+  const outputRoot = await mkdtemp(path2.join(tmpdir(), "agora-legato-lowering-"));
+  const kernelPath = getArtifactTextPath(kernelArtifact);
+  const stages = process.env.AGORA_LOWERING_STAGES ?? "MLIR,CORE_IR,BACKEND_IR,ASM,BINARY";
+  const timeoutMs = readPositiveInt(process.env.AGORA_LOWERING_TIMEOUT_MS, DEFAULT_LOWERING_TIMEOUT_MS);
+  const env = loweringWorkerEnv(activeRuntime);
+  try {
+    const output = await spawnLoweringProcess(python, [
+      runnerPath,
+      "--kernel",
+      kernelPath,
+      "--output-root",
+      outputRoot,
+      "--stages",
+      stages
+    ], {
+      cwd: sdkRoot,
+      env,
+      timeoutMs,
+      updateLiveRun: updateLiveRun ? async (stdout, stderr) => {
+        await updateLiveRun({
+          status: "running",
+          stdout: sanitizeWorkerOutput(stdout),
+          stderr: sanitizeWorkerOutput(stderr),
+          completedStage: parseCompletedStage(stdout),
+          failedStage: parseFailedStage(`${stdout}
+${stderr}`),
+          ...runtimeMetadata
+        });
+      } : void 0
+    });
+    return {
+      status: "success",
+      exitCode: 0,
+      stdout: sanitizeWorkerOutput(output.stdout),
+      stderr: sanitizeWorkerOutput(output.stderr),
+      completedStage: parseCompletedStage(output.stdout),
+      generatedArtifacts: await listGeneratedArtifacts(outputRoot),
+      generatedArtifactFiles: await collectGeneratedArtifactFiles(outputRoot),
+      ...runtimeMetadata,
+      generatedArtifactHash: await hashGeneratedArtifacts(outputRoot, parseCompletedStage(output.stdout))
+    };
+  } catch (error) {
+    const failure = error;
+    const stdout = sanitizeWorkerOutput(failure.stdout ?? "");
+    const timeoutNote = failure.killed || failure.signal === "SIGTERM" ? `lowering worker timed out after ${timeoutMs}ms` : "";
+    const stderr = sanitizeWorkerOutput([failure.stderr, timeoutNote, failure.message ?? "unknown lowering failure"].filter(Boolean).join("\n"));
+    return {
+      status: "failed",
+      exitCode: typeof failure.code === "number" ? failure.code : 1,
+      stdout,
+      stderr,
+      failedStage: parseFailedStage(`${stdout}
+${stderr}`),
+      completedStage: parseCompletedStage(stdout),
+      generatedArtifacts: await listGeneratedArtifacts(outputRoot),
+      generatedArtifactFiles: await collectGeneratedArtifactFiles(outputRoot),
+      ...runtimeMetadata,
+      generatedArtifactHash: await hashGeneratedArtifacts(outputRoot, parseCompletedStage(stdout))
+    };
+  } finally {
+    await rm(outputRoot, { recursive: true, force: true });
+  }
+}
+async function spawnLoweringProcess(command, args, options) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let lastUpdateAt = 0;
+    const flush = () => {
+      if (!options.updateLiveRun) return;
+      const nowMs = Date.now();
+      if (nowMs - lastUpdateAt < 1500) return;
+      lastUpdateAt = nowMs;
+      void options.updateLiveRun(stdout, stderr);
+    };
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      child.kill("SIGTERM");
+    }, options.timeoutMs);
+    timeout.unref();
+    child.stdout?.on("data", (chunk) => {
+      stdout += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+      flush();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+      flush();
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(Object.assign(error, { stdout, stderr }));
+    });
+    child.on("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      void (async () => {
+        if (options.updateLiveRun) await options.updateLiveRun(stdout, stderr);
+        if (code === 0) {
+          resolve({ stdout, stderr });
+          return;
+        }
+        reject({
+          code: typeof code === "number" ? code : 1,
+          signal,
+          killed: signal === "SIGTERM",
+          stdout,
+          stderr,
+          message: `lowering worker exited with ${typeof code === "number" ? `code ${code}` : `signal ${signal ?? "unknown"}`}`
+        });
+      })();
+    });
+  });
+}
+function sdkRuntimeMetadata(runtime, status) {
+  return {
+    sdkRepoUrl: runtime.repoUrl,
+    sdkBranch: runtime.branch,
+    sdkCommitSha: status.commitSha,
+    sdkPreparedRoot: runtime.preparedRoot
+  };
+}
+function sdkRuntimeExecutionView(runtime, status) {
+  if (status.status !== "ready") return runtime;
+  return {
+    ...runtime,
+    preparedRoot: status.preparedRoot,
+    pythonPath: status.pythonPath,
+    extraPythonPaths: path2.join(status.preparedRoot, "legato_aten_lib")
+  };
+}
+function readPositiveInt(value, fallback) {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+async function hashGeneratedArtifacts(root, completedStage) {
+  if (!completedStage) return void 0;
+  const stageRoot = stageBasis(completedStage) ? path2.join(root, completedStage.toLowerCase()) : root;
+  const files = await listGeneratedArtifacts(stageRoot);
+  if (files.length === 0) return void 0;
+  const hash = createHash("sha256");
+  for (const relativePath of files) {
+    const filePath = path2.join(stageRoot, relativePath);
+    const bytes = await readFile2(filePath);
+    hash.update(relativePath);
+    hash.update("\0");
+    hash.update(normalizeArtifactBytes(relativePath, bytes));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+function normalizeArtifactBytes(relativePath, bytes) {
+  const extension = path2.extname(relativePath).toLowerCase();
+  if (![".mlir", ".ll", ".s", ".asm", ".txt"].includes(extension)) return bytes;
+  return Buffer.from(bytes.toString("utf8").replace(/0x[a-fA-F0-9]+/g, "<addr>").replace(/[ \t]+/g, " ").replace(/\r\n/g, "\n").trim(), "utf8");
+}
+function buildVerificationFingerprint(result, kernelArtifact, createdAt) {
+  const diagnosticSignature = normalizeSignatureText(`${result.failedStage ?? ""}
+${result.stdout}
+${result.stderr}`).slice(0, 240);
+  const basis = stageBasis(result.completedStage) ?? (result.failedStage ? "diagnostic" : "raw");
+  const artifactHash = result.generatedArtifactHash ?? kernelArtifact?.checksum;
+  if (!artifactHash && !diagnosticSignature) return void 0;
+  const key = createHash("sha256").update(["lowering", basis, result.completedStage ?? "none", result.failedStage ?? "none", artifactHash ?? "no-artifact", diagnosticSignature].join("\0")).digest("hex");
+  return {
+    key,
+    basis,
+    lastSuccessfulStage: result.completedStage,
+    failedStage: result.failedStage,
+    artifactHash,
+    diagnosticSignature: diagnosticSignature || void 0,
+    createdAt
+  };
+}
+function stageBasis(stage) {
+  if (stage === "MLIR") return "mlir";
+  if (stage === "CORE_IR") return "core-ir";
+  if (stage === "BACKEND_IR") return "backend-ir";
+  if (stage === "ASM") return "asm";
+  if (stage === "BINARY") return "binary";
+  return void 0;
+}
+function normalizeSignatureText(text) {
+  return text.toLowerCase().replace(/[a-f0-9]{16,}/g, "<hash>").replace(/0x[a-f0-9]+/g, "<addr>").replace(/\d+/g, "<num>").replace(/\s+/g, " ").trim();
+}
+function sanitizeWorkerOutput(output) {
+  const redacted = output.replace(/([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY|CREDENTIAL)[A-Z0-9_]*=)[^\s]+/gi, "$1[redacted]").replace(/(Bearer\s+)[A-Za-z0-9._~+/-]+=*/gi, "$1[redacted]");
+  return redacted.length > 512 * 1024 ? `${redacted.slice(0, 512 * 1024)}
+[truncated]
+` : redacted;
+}
+function parseFailedStage(output) {
+  const matches = [...output.matchAll(/\[LEGATO_WORKER\] stage=([A-Z_]+) status=running/g)];
+  return matches.at(-1)?.[1];
+}
+function parseCompletedStage(output) {
+  const matches = [...output.matchAll(/\[LEGATO_WORKER\] stage=([A-Z_]+) status=success/g)];
+  return matches.at(-1)?.[1];
+}
+async function findExecutable(envPath, fallback) {
+  if (envPath) {
+    try {
+      await access2(envPath);
+      return envPath;
+    } catch {
+      return void 0;
+    }
+  }
+  try {
+    const output = await execFileAsync("which", [fallback], { timeout: 2e3 });
+    return output.stdout.trim() || void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function pathExists(candidate) {
+  try {
+    await access2(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function commandVersion(command) {
+  try {
+    const output = await execFileAsync(command, ["--version"], { timeout: 2e3, maxBuffer: 64 * 1024 });
+    return output.stdout.trim() || output.stderr.trim() || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildLog(input) {
+  const commandLabel = `${path2.basename(input.plan.command)} ${input.plan.args.join(" ")}`;
+  const lines = [
+    `issue: ${input.issueId}`,
+    `kind: ${input.kind}`,
+    `mode: ${input.mode}`,
+    `status: ${input.result.status}`,
+    `startedAt: ${input.startedAt}`,
+    `completedAt: ${input.completedAt}`,
+    `cwd: ${input.plan.cwd}`,
+    `command: ${commandLabel}`,
+    `reason: ${input.plan.reason}`,
+    `sourceArtifactId: ${input.sourceArtifactId ?? "current bundle kernel"}`,
+    `kernelArtifact: ${input.kernelArtifact ? `${input.kernelArtifact.filename} (${getArtifactTextPath(input.kernelArtifact)})` : "missing"}`,
+    `coreIrArtifact: ${input.coreIrArtifact ? `${input.coreIrArtifact.filename} (${getArtifactTextPath(input.coreIrArtifact)})` : "missing"}`,
+    `environment.LEGATO_OPT: ${process.env.LEGATO_OPT ? "set" : "unset"}`,
+    `environment.AGORA_SDK_ROOT: ${process.env.AGORA_SDK_ROOT ? "set" : "unset"}`,
+    `environment.AGORA_LOWERING_STAGES: ${process.env.AGORA_LOWERING_STAGES ?? "default"}`,
+    `environment.AGORA_FSIM_DEVICE_VERSION: ${process.env.AGORA_FSIM_DEVICE_VERSION ?? "default"}`,
+    `environment.AGORA_FSIM_COMPUTE_MODE: ${process.env.AGORA_FSIM_COMPUTE_MODE ?? "default"}`,
+    `environment.AGORA_ISSUE_STORE: ${process.env.AGORA_ISSUE_STORE ? "set" : "unset"}`,
+    `exitCode: ${typeof input.result.exitCode === "number" ? input.result.exitCode : "not-run"}`,
+    `toolVersion: ${input.result.toolVersion ?? "unknown"}`,
+    `sdk.repoUrl: ${input.result.sdkRepoUrl ?? "unknown"}`,
+    `sdk.branch: ${input.result.sdkBranch ?? "unknown"}`,
+    `sdk.commitSha: ${input.result.sdkCommitSha ?? "unknown"}`,
+    `sdk.preparedRoot: ${input.result.sdkPreparedRoot ?? "unknown"}`,
+    "",
+    "skippedEvidence:",
+    ...(input.result.skippedEvidence ?? ["none"]).map((item) => `- ${item}`),
+    "",
+    "failedStage:",
+    input.result.failedStage ?? "none",
+    "completedStage:",
+    input.result.completedStage ?? "none",
+    "",
+    "generatedArtifacts:",
+    ...input.result.generatedArtifacts?.length ? input.result.generatedArtifacts.map((item) => `- ${item}`) : ["none"],
+    "",
+    "stdout:",
+    input.result.stdout || "<empty>",
+    "",
+    "stderr:",
+    input.result.stderr || "<empty>"
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function verificationSummary(kind, result, reason) {
+  if (kind === "lowering" && result.status === "success") {
+    const stage = result.completedStage ? `${result.completedStage} \uB2E8\uACC4\uAE4C\uC9C0` : "\uC694\uCCAD\uB41C \uB2E8\uACC4\uAE4C\uC9C0";
+    return `\uC790\uB3D9 lowering\uC774 ${stage} \uC131\uACF5\uD588\uC2B5\uB2C8\uB2E4. \uC0DD\uC131\uB41C \uC0B0\uCD9C\uBB3C ${result.generatedArtifacts?.length ?? 0}\uAC1C\uB97C verification-output artifact\uB85C \uCCA8\uBD80\uD588\uC2B5\uB2C8\uB2E4.`;
+  }
+  if (kind === "lowering" && result.status === "failed") {
+    if (result.exitCode === 2) {
+      return "\uC790\uB3D9 lowering preflight\uAC00 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. \uCEE4\uB110 \uD568\uC218/Legato annotation/\uC778\uC790 \uD569\uC131 \uC624\uB958\uB294 verification-output \uB85C\uADF8\uB97C \uD655\uC778\uD558\uC138\uC694.";
+    }
+    const stage = result.failedStage ? `${result.failedStage} \uB2E8\uACC4` : "\uC54C \uC218 \uC5C6\uB294 \uB2E8\uACC4";
+    return `\uC790\uB3D9 lowering\uC774 ${stage}\uC5D0\uC11C \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. \uC804\uCCB4 stdout/stderr\uC640 traceback\uC740 verification-output \uB85C\uADF8\uB97C \uD655\uC778\uD558\uC138\uC694.`;
+  }
+  if (kind === "fsim" && result.status === "success") {
+    return `\uC790\uB3D9 fSIM \uC2E4\uD589\uC774 \uC131\uACF5\uD588\uC2B5\uB2C8\uB2E4. \uC0DD\uC131\uB41C \uC0B0\uCD9C\uBB3C ${result.generatedArtifacts?.length ?? 0}\uAC1C\uB97C verification-output artifact\uB85C \uCCA8\uBD80\uD588\uC2B5\uB2C8\uB2E4.`;
+  }
+  if (kind === "fsim" && result.status === "failed") {
+    return "\uC790\uB3D9 fSIM \uC2E4\uD589\uC774 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. Python launcher stdout/stderr\uC640 HART fSIM \uC124\uC815 \uB85C\uADF8\uB294 verification-output \uB85C\uADF8\uB97C \uD655\uC778\uD558\uC138\uC694.";
+  }
+  return `Verification ${kind} ${result.status}. ${reason} See verification-output log.`;
+}
+export {
+  maybeRunAutoLowering,
+  runIssueVerification
+};