@hardkas/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,3420 @@
+#!/usr/bin/env node
+import {
+  UI,
+  handleError
+} from "./chunk-M54KNJEH.js";
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/runners/up-runner.ts
+import { loadHardkasConfig } from "@hardkas/config";
+import { JsonWrpcKaspaClient } from "@hardkas/kaspa-rpc";
+import { listHardkasAccounts } from "@hardkas/accounts";
+import fs from "fs/promises";
+import path from "path";
+async function runUp() {
+  UI.box("HardKAS", "Environment Bootstrapper");
+  try {
+    const loaded = await loadHardkasConfig();
+    const networkId = loaded.config.defaultNetwork || "simulated";
+    UI.info(`\x1B[1mNetwork Mode:\x1B[0m ${networkId} (${loaded.config.networks?.[networkId]?.kind || "default"})`);
+    UI.info(`\x1B[1mConfig:\x1B[0m       ${loaded.path || "defaults"}`);
+    console.log("");
+    const runtimeDir = path.join(loaded.cwd, ".hardkas", "runtime");
+    const receiptsDir = path.join(loaded.cwd, ".hardkas", "receipts");
+    await fs.mkdir(runtimeDir, { recursive: true });
+    await fs.mkdir(receiptsDir, { recursive: true });
+    UI.info("\x1B[1mRuntime:\x1B[0m");
+    const target = loaded.config.networks?.[networkId];
+    let rpcUrl = "ws://127.0.0.1:18210";
+    if (target) {
+      if (target.kind === "kaspa-rpc" || target.kind === "igra") {
+        rpcUrl = target.rpcUrl;
+      } else if (target.kind === "kaspa-node" && target.rpcUrl) {
+        rpcUrl = target.rpcUrl;
+      }
+    }
+    const client = new JsonWrpcKaspaClient({ rpcUrl });
+    try {
+      const health = await client.healthCheck();
+      if (health.reachable) {
+        UI.success(`RPC available at ${rpcUrl}`);
+      } else {
+        console.log(`  \x1B[33m\u26A0\x1B[0m RPC not reachable at ${rpcUrl}. Run 'hardkas node start' or check kaspad.`);
+      }
+    } catch (e) {
+      console.log(`  \x1B[33m\u26A0\x1B[0m RPC check failed: ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      await client.close();
+    }
+    UI.success(`State directory:    .hardkas/runtime`);
+    UI.success(`Receipts directory: .hardkas/receipts`);
+    console.log("");
+    UI.info("\x1B[1mAccounts:\x1B[0m");
+    const accounts = listHardkasAccounts(loaded.config);
+    if (accounts.length > 0) {
+      for (const acc of accounts) {
+        UI.success(`${acc.name} (${acc.kind})`);
+      }
+    } else {
+      console.log("  No accounts defined in config.");
+    }
+    console.log("");
+    UI.info("\x1B[32m\u2713\x1B[0m \x1B[1mHardKAS is UP and ready for development.\x1B[0m");
+    UI.footer("Try running: pnpm example:localnet");
+  } catch (error) {
+    throw error;
+  }
+}
+
+// src/commands/init.ts
+function registerInitCommands(program) {
+  program.command("init").description("Initialize a new HardKAS project").argument("[name]", "Project name or directory").option("--force", "Overwrite existing hardkas.config.ts", false).action(async (name, options) => {
+    try {
+      const fs10 = await import("fs");
+      const path11 = await import("path");
+      let targetDir = process.cwd();
+      if (name) {
+        targetDir = path11.join(process.cwd(), name);
+        if (!fs10.existsSync(targetDir)) {
+          fs10.mkdirSync(targetDir, { recursive: true });
+        }
+      }
+      const configFile = path11.join(targetDir, "hardkas.config.ts");
+      const pkgFile = path11.join(targetDir, "package.json");
+      if (fs10.existsSync(configFile) && !options.force) {
+        UI.warning(`hardkas.config.ts already exists in ${name || "current directory"}. Use --force to overwrite.`);
+        return;
+      }
+      if (!fs10.existsSync(pkgFile)) {
+        const pkgTemplate = {
+          name: name || "hardkas-project",
+          version: "1.0.0",
+          type: "module",
+          dependencies: {
+            "@hardkas/sdk": "latest"
+          }
+        };
+        fs10.writeFileSync(pkgFile, JSON.stringify(pkgTemplate, null, 2), "utf-8");
+        UI.info("Created: package.json");
+      }
+      const template = `import { defineHardkasConfig } from "@hardkas/sdk";
+
+export default defineHardkasConfig({
+  // HardKAS v0.2-alpha Configuration
+  defaultNetwork: "simnet",
+
+  networks: {
+    simnet: {
+      kind: "simulated"
+    },
+
+    node: {
+      kind: "kaspa-node",
+      network: "simnet",
+      rpcUrl: "ws://127.0.0.1:18210"
+    }
+  },
+
+  accounts: {
+    alice: {
+      kind: "simulated",
+      address: "kaspasim:sim_alice"
+    },
+    bob: {
+      kind: "simulated",
+      address: "kaspasim:sim_bob"
+    }
+  }
+});
+`;
+      fs10.writeFileSync(configFile, template, "utf-8");
+      UI.success(`HardKAS project '${name || "current"}' initialized successfully.`);
+      if (name) UI.info(`Project folder: ${targetDir}`);
+      UI.info(`Created: hardkas.config.ts (v0.2-alpha)`);
+      UI.footer(`Run 'cd ${name || "."}' and then 'hardkas up' to start.`);
+    } catch (e) {
+      handleError(e, "Initialization failed");
+      process.exitCode = 1;
+    }
+  });
+  program.command("up").description("Boot or validate the HardKAS developer runtime environment").action(async () => {
+    try {
+      await runUp();
+    } catch (e) {
+      handleError(e, "Bootstrap failed");
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/tx.ts
+import { bigIntReplacer } from "@hardkas/artifacts";
+
+// src/runners/tx-profile-runner.ts
+import { readArtifact } from "@hardkas/artifacts";
+import { estimateTransactionMass } from "@hardkas/tx-builder";
+import { formatSompi } from "@hardkas/core";
+import path2 from "path";
+async function runTxProfile(options) {
+  const absolutePath = path2.resolve(process.cwd(), options.path);
+  const plan = await readArtifact(absolutePath);
+  if (plan.schema !== "hardkas.txPlan" && plan.schema !== "hardkas.txPlan.v1") {
+    throw new Error(`Artifact at ${options.path} is not a valid transaction plan.`);
+  }
+  const result = estimateTransactionMass({
+    inputCount: plan.inputs.length,
+    outputs: plan.outputs,
+    hasChange: !!plan.change
+  });
+  UI.header(`Transaction Profile: ${path2.basename(options.path)}`);
+  console.log("Summary:");
+  console.log(`  Plan ID:    ${plan.planId}`);
+  console.log(`  Network:    ${plan.networkId}`);
+  console.log(`  Amount:     ${formatSompi(BigInt(plan.amountSompi))} (${plan.amountSompi} sompi)`);
+  console.log(`  Total Mass: ${result.mass}`);
+  console.log(`  Est. Fee:   ${formatSompi(BigInt(plan.estimatedFeeSompi))} (${plan.estimatedFeeSompi} sompi)`);
+  console.log("\nMass Breakdown:");
+  console.log(`  Base Transaction:  ${result.breakdown.base.toString().padStart(5)}`);
+  console.log(`  Inputs (${plan.inputs.length}):       ${result.breakdown.inputs.toString().padStart(5)}`);
+  console.log(`  Outputs (${plan.outputs.length + (plan.change ? 1 : 0)}):      ${result.breakdown.outputs.toString().padStart(5)}`);
+  if (result.breakdown.payload > 0n) {
+    console.log(`  Payload:           ${result.breakdown.payload.toString().padStart(5)}`);
+  }
+  console.log(`  -----------------------`);
+  console.log(`  Total:             ${result.mass.toString().padStart(5)}`);
+  if (result.warnings.length > 0) {
+    console.log("\x1B[33m\nWarnings:\x1B[0m");
+    result.warnings.forEach((w) => console.log(`  [!] ${w}`));
+  }
+  console.log("\nStructure:");
+  console.log(`  Inputs:  ${plan.inputs.length}`);
+  plan.inputs.forEach((i, idx) => {
+    console.log(`    [${idx}] ${i.outpoint.transactionId.substring(0, 8)}...:${i.outpoint.index} (${formatSompi(BigInt(i.amountSompi))})`);
+  });
+  console.log(`  Outputs: ${plan.outputs.length + (plan.change ? 1 : 0)}`);
+  plan.outputs.forEach((o, idx) => {
+    console.log(`    [${idx}] ${o.address.substring(0, 20)}... (${formatSompi(BigInt(o.amountSompi))})`);
+  });
+  if (plan.change) {
+    console.log(`    [C] ${plan.change.address.substring(0, 20)}... (${formatSompi(BigInt(plan.change.amountSompi))}) [CHANGE]`);
+  }
+  console.log("\nNote: Mass estimation is protocol-aware (v0.2-alpha best-effort).");
+}
+
+// src/runners/tx-plan-runner.ts
+import {
+  parseKasToSompi
+} from "@hardkas/core";
+import {
+  resolveHardkasAccountAddress
+} from "@hardkas/accounts";
+import {
+  buildPaymentPlan
+} from "@hardkas/tx-builder";
+import {
+  createTxPlanArtifact
+} from "@hardkas/artifacts";
+import { coreEvents } from "@hardkas/core";
+import {
+  resolveNetworkTarget
+} from "@hardkas/config";
+async function runTxPlan(input) {
+  const { from, to, amount, networkId, feeRate, config, url } = input;
+  const fromAddress = resolveHardkasAccountAddress(from, config);
+  const toAddress = resolveHardkasAccountAddress(to, config);
+  const amountSompi = parseKasToSompi(amount);
+  const feeRateSompiPerMass = BigInt(feeRate);
+  let availableUtxos = [];
+  let mode = "simulated";
+  let rpcUrl;
+  let resolvedNetwork = networkId;
+  try {
+    const { target, name } = resolveNetworkTarget({ config, network: networkId });
+    resolvedNetwork = name;
+    if (target.kind === "simulated") {
+      const { loadOrCreateLocalnetState: loadOrCreateLocalnetState3, getSpendableUtxos } = await import("@hardkas/localnet");
+      const localState = await loadOrCreateLocalnetState3();
+      const unspent = getSpendableUtxos(localState, fromAddress);
+      availableUtxos = unspent.map((u) => ({
+        outpoint: {
+          transactionId: u.id.split(":")[0],
+          index: Number(u.id.split(":")[2]) || 0
+        },
+        address: u.address,
+        amountSompi: BigInt(u.amountSompi),
+        scriptPublicKey: "mock-script"
+      }));
+      mode = "simulated";
+    } else if (target.kind === "kaspa-node" || target.kind === "kaspa-rpc") {
+      const { JsonWrpcKaspaClient: JsonWrpcKaspaClient4 } = await import("@hardkas/kaspa-rpc");
+      const { resolveRuntimeConfig } = await import("@hardkas/node-orchestrator");
+      rpcUrl = url || target.rpcUrl;
+      if (!rpcUrl && target.kind === "kaspa-node") {
+        rpcUrl = resolveRuntimeConfig({
+          network: target.network,
+          ...target.dataDir ? { dataDir: target.dataDir } : {}
+        }).rpcUrl;
+      }
+      if (!rpcUrl) throw new Error("Could not resolve RPC URL");
+      const client = new JsonWrpcKaspaClient4({ rpcUrl });
+      const rpcUtxos = await client.getUtxosByAddress(fromAddress);
+      await client.close();
+      availableUtxos = rpcUtxos.map((u) => ({
+        outpoint: u.outpoint,
+        address: u.address,
+        amountSompi: u.amountSompi,
+        scriptPublicKey: u.scriptPublicKey || "unresolved"
+      }));
+      mode = target.kind;
+    }
+  } catch (e) {
+    if (url || networkId !== "simnet") {
+      const { JsonWrpcKaspaClient: JsonWrpcKaspaClient4 } = await import("@hardkas/kaspa-rpc");
+      const { resolveRuntimeConfig } = await import("@hardkas/node-orchestrator");
+      rpcUrl = url;
+      if (!rpcUrl) {
+        rpcUrl = resolveRuntimeConfig({ network: networkId }).rpcUrl;
+      }
+      const client = new JsonWrpcKaspaClient4({ rpcUrl });
+      const rpcUtxos = await client.getUtxosByAddress(fromAddress);
+      await client.close();
+      availableUtxos = rpcUtxos.map((u) => ({
+        outpoint: u.outpoint,
+        address: u.address,
+        amountSompi: u.amountSompi,
+        scriptPublicKey: u.scriptPublicKey || "unresolved"
+      }));
+      mode = "kaspa-rpc";
+    } else {
+      throw e;
+    }
+  }
+  if (availableUtxos.length === 0) {
+    throw new Error(`No UTXOs found for ${fromAddress} on network '${resolvedNetwork}'.`);
+  }
+  const plan = buildPaymentPlan({
+    fromAddress,
+    outputs: [{ address: toAddress, amountSompi }],
+    availableUtxos,
+    feeRateSompiPerMass
+  });
+  const artifact = createTxPlanArtifact({
+    networkId: resolvedNetwork,
+    mode: mode === "simulated" ? "simulated" : "real",
+    ...rpcUrl ? { rpcUrl } : {},
+    from: { input: from, address: fromAddress },
+    to: { input: to, address: toAddress },
+    amountSompi,
+    plan
+  });
+  coreEvents.normalizeAndEmit({
+    kind: "workflow.plan.created",
+    planId: artifact.planId,
+    planHash: artifact.contentHash || "unknown",
+    network: artifact.networkId,
+    mode: artifact.mode
+  });
+  return artifact;
+}
+
+// src/runners/tx-sign-runner.ts
+import {
+  resolveHardkasAccount,
+  signTxPlanArtifact
+} from "@hardkas/accounts";
+async function runTxSign(input) {
+  const { planArtifact, accountName, config, allowMainnetSigning } = input;
+  const targetAccountName = accountName || planArtifact.from.accountName || planArtifact.from.input || planArtifact.from.address;
+  const account = resolveHardkasAccount({ nameOrAddress: targetAccountName, config });
+  const signedArtifact = await signTxPlanArtifact({
+    planArtifact,
+    account,
+    config,
+    allowMainnet: allowMainnetSigning ?? false
+  });
+  return signedArtifact;
+}
+
+// src/runners/tx-send-runner.ts
+import {
+  getBroadcastableSignedTransaction,
+  HARDKAS_VERSION,
+  ARTIFACT_SCHEMAS,
+  ARTIFACT_VERSION
+} from "@hardkas/artifacts";
+import { coreEvents as coreEvents2 } from "@hardkas/core";
+import {
+  resolveNetworkTarget as resolveNetworkTarget2
+} from "@hardkas/config";
+import {
+  JsonWrpcKaspaClient as JsonWrpcKaspaClient2
+} from "@hardkas/kaspa-rpc";
+import {
+  loadOrCreateLocalnetState,
+  saveLocalnetState,
+  applySimulatedPayment,
+  saveSimulatedReceipt,
+  saveSimulatedTrace
+} from "@hardkas/localnet";
+
+// src/broadcast-guard.ts
+function assertBroadcastNetworkAllowed(input) {
+  const isMainnetArtifact = isMainnetLike(input.artifactNetworkId);
+  const isMainnetSelected = isMainnetLike(input.selectedNetwork);
+  if (isMainnetArtifact || isMainnetSelected) {
+    throw new Error(
+      "Mainnet broadcast is disabled in HardKAS v0.2-alpha.\n\nReason:\n  Production transaction submission is intentionally unavailable in this development release.\n\nUse:\n  simnet or testnet for real transaction testing."
+    );
+  }
+  if (!isSameNetwork(input.artifactNetworkId, input.selectedNetwork)) {
+    throw new Error(
+      `Network mismatch: signed artifact targets '${input.artifactNetworkId}' but CLI selected '${input.selectedNetwork}'.`
+    );
+  }
+}
+function isMainnetLike(network) {
+  const n = network.toLowerCase();
+  return n === "mainnet" || n === "kaspa" || n === "kaspa-mainnet";
+}
+function isSameNetwork(n1, n2) {
+  if (n1 === n2) return true;
+  if (isMainnetLike(n1) && isMainnetLike(n2)) return true;
+  return false;
+}
+
+// src/runners/tx-send-runner.ts
+async function runTxSend(input) {
+  const { signedArtifact, network, config, url } = input;
+  const broadcastable = getBroadcastableSignedTransaction(signedArtifact);
+  const networkName = network || signedArtifact.networkId;
+  const { name: resolvedName, target } = resolveNetworkTarget2({ network: networkName, config });
+  if (target.kind === "simulated") {
+    const state = await loadOrCreateLocalnetState();
+    const startTime = Date.now();
+    const events = [
+      { type: "phase.started", phase: "send", timestamp: startTime }
+    ];
+    const simResult = applySimulatedPayment(state, {
+      from: signedArtifact.from.input || signedArtifact.from.address,
+      to: signedArtifact.to.input || signedArtifact.to.address,
+      amountSompi: BigInt(signedArtifact.amountSompi)
+    });
+    coreEvents2.normalizeAndEmit({
+      kind: "workflow.submitted",
+      txId: simResult.receipt.txId,
+      endpoint: "simulated://local"
+    });
+    events.push({ type: "phase.completed", phase: "send", timestamp: Date.now() });
+    await saveLocalnetState(simResult.state);
+    const receiptPath = await saveSimulatedReceipt(simResult.receipt);
+    const receipt = {
+      schema: ARTIFACT_SCHEMAS.TX_RECEIPT,
+      hardkasVersion: HARDKAS_VERSION,
+      version: ARTIFACT_VERSION,
+      networkId: resolvedName,
+      mode: "simulated",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      status: "confirmed",
+      txId: simResult.receipt.txId,
+      sourceSignedId: signedArtifact.signedId,
+      from: { address: signedArtifact.from.address },
+      to: { address: signedArtifact.to.address },
+      amountSompi: signedArtifact.amountSompi,
+      feeSompi: simResult.receipt.feeSompi,
+      daaScore: simResult.receipt.daaScore.toString(),
+      submittedAt: simResult.receipt.createdAt,
+      confirmedAt: simResult.receipt.createdAt,
+      rpcUrl: "simulated://local"
+    };
+    const tracePath = await saveSimulatedTrace({
+      schema: ARTIFACT_SCHEMAS.TX_TRACE,
+      hardkasVersion: HARDKAS_VERSION,
+      version: ARTIFACT_VERSION,
+      createdAt: receipt.createdAt,
+      txId: receipt.txId,
+      mode: "simulated",
+      networkId: resolvedName,
+      events,
+      receiptPath
+    });
+    receipt.tracePath = tracePath;
+    return {
+      accepted: true,
+      txId: receipt.txId,
+      rpcUrl: url || "simulated://local",
+      networkName: resolvedName,
+      receipt,
+      receiptPath,
+      formatted: `Transaction sent in simulated localnet
+Tx ID: ${receipt.txId}
+Receipt: ${receiptPath}`
+    };
+  }
+  assertBroadcastNetworkAllowed({
+    artifactNetworkId: signedArtifact.networkId,
+    selectedNetwork: networkName
+  });
+  const rpcUrl = url || target.rpcUrl;
+  if (!rpcUrl) throw new Error(`No RPC URL found for network '${networkName}'.`);
+  const client = new JsonWrpcKaspaClient2({ rpcUrl });
+  try {
+    const txId = broadcastable.rawTransaction?.id || "unknown";
+    coreEvents2.normalizeAndEmit({
+      kind: "workflow.submitted",
+      txId,
+      endpoint: rpcUrl
+    });
+    const result = await client.submitTransaction(broadcastable.rawTransaction);
+    const receipt = {
+      schema: ARTIFACT_SCHEMAS.TX_RECEIPT,
+      hardkasVersion: HARDKAS_VERSION,
+      version: ARTIFACT_VERSION,
+      networkId: resolvedName,
+      mode: "real",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      status: result.accepted ? "submitted" : "failed",
+      txId: result.transactionId || "failed",
+      sourceSignedId: signedArtifact.signedId,
+      from: { address: signedArtifact.from.address },
+      to: { address: signedArtifact.to.address },
+      amountSompi: signedArtifact.amountSompi,
+      feeSompi: signedArtifact.metadata?.estimatedFeeSompi || "0",
+      submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      rpcUrl
+    };
+    return {
+      accepted: !!result.accepted,
+      txId: receipt.txId,
+      rpcUrl,
+      networkName: resolvedName,
+      receipt,
+      formatted: result.accepted ? `Kaspa transaction broadcast
+Network: ${resolvedName}
+Tx ID:   ${receipt.txId}` : `Transaction failed: ${JSON.stringify(result.raw)}`
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+// src/runners/tx-flow.ts
+import {
+  writeArtifact
+} from "@hardkas/artifacts";
+import path3 from "path";
+import fs2 from "fs";
+async function runTxFlow(input) {
+  const {
+    from,
+    to,
+    amount,
+    network,
+    config,
+    url,
+    feeRate,
+    planOnly,
+    sign,
+    send,
+    yes,
+    outDir,
+    name,
+    allowMainnetSigning
+  } = input;
+  if (planOnly && (sign || send)) {
+    throw new Error("--plan-only cannot be combined with --sign or --send.");
+  }
+  const shouldSign = sign || send;
+  const shouldSend = send;
+  const flowResult = {
+    ok: true,
+    networkId: network || config.defaultNetwork || "simnet",
+    mode: "unknown",
+    steps: {
+      plan: { status: "skipped" },
+      sign: { status: "skipped" },
+      send: { status: "skipped" }
+    },
+    result: "planned-only"
+  };
+  try {
+    const planArtifact = await runTxPlan({
+      from,
+      to,
+      amount,
+      networkId: flowResult.networkId,
+      feeRate,
+      config,
+      ...url ? { url } : {}
+    });
+    flowResult.mode = planArtifact.mode;
+    flowResult.networkId = planArtifact.networkId;
+    flowResult.steps.plan = { status: "ok", artifact: planArtifact };
+    if (outDir) {
+      const planPath = await saveArtifact(planArtifact, outDir, name, "plan", from, to, amount);
+      flowResult.steps.plan.artifactPath = planPath;
+    }
+    if (planOnly) {
+      flowResult.result = "planned-only";
+      return flowResult;
+    }
+    if (shouldSign) {
+      if (shouldSend && !yes && planArtifact.mode !== "simulated") {
+        flowResult.steps.sign = {
+          status: "blocked",
+          reason: "--yes is required before signing/sending a real transaction flow."
+        };
+        flowResult.steps.send = { status: "blocked", reason: "sign blocked" };
+        flowResult.result = "planned-only";
+        flowResult.ok = false;
+        return flowResult;
+      }
+      const signedArtifact = await runTxSign({
+        planArtifact,
+        config,
+        ...allowMainnetSigning !== void 0 ? { allowMainnetSigning } : {}
+      });
+      flowResult.steps.sign = { status: "ok", artifact: signedArtifact };
+      flowResult.result = "signed";
+      if (outDir) {
+        const signedPath = await saveArtifact(signedArtifact, outDir, name, "signed", from, to, amount);
+        flowResult.steps.sign.artifactPath = signedPath;
+      }
+      if (shouldSend) {
+        if (!yes) {
+          flowResult.steps.send = { status: "blocked", reason: "--yes is required to broadcast" };
+          flowResult.result = "signed";
+          flowResult.ok = false;
+        } else {
+          const sendResult = await runTxSend({
+            signedArtifact,
+            config,
+            ...url ? { url } : {}
+          });
+          flowResult.steps.send = { status: "ok", artifact: sendResult };
+          flowResult.result = "broadcast";
+        }
+      }
+    } else {
+      flowResult.steps.sign = { status: "skipped", reason: "re-run with --sign to create a signed artifact" };
+      flowResult.steps.send = { status: "skipped", reason: "re-run with --send --yes to broadcast" };
+    }
+  } catch (error) {
+    flowResult.ok = false;
+    const msg = error instanceof Error ? error.message : String(error);
+    if (flowResult.steps.plan.status !== "ok") {
+      flowResult.steps.plan = { status: "error", error: msg };
+    } else if (shouldSign && flowResult.steps.sign.status !== "ok") {
+      flowResult.steps.sign = { status: "error", error: msg };
+    } else if (shouldSend && flowResult.steps.send.status !== "ok") {
+      flowResult.steps.send = { status: "error", error: msg };
+    }
+  }
+  return flowResult;
+}
+async function saveArtifact(artifact, outDir, baseName, suffix, from, to, amount) {
+  if (!fs2.existsSync(outDir)) {
+    fs2.mkdirSync(outDir, { recursive: true });
+  }
+  let fileName = "";
+  if (baseName) {
+    fileName = `${baseName}.${suffix}.json`;
+  } else {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const sanitizedFrom = from.replace(/[^a-z0-9]/gi, "_").substring(0, 10);
+    const sanitizedTo = to.replace(/[^a-z0-9]/gi, "_").substring(0, 10);
+    fileName = `${timestamp}-${sanitizedFrom}-to-${sanitizedTo}-${amount}.${suffix}.json`;
+  }
+  const fullPath = path3.join(outDir, fileName);
+  await writeArtifact(fullPath, artifact);
+  return fullPath;
+}
+
+// src/runners/tx-receipt-runner.ts
+import {
+  loadSimulatedReceipt
+} from "@hardkas/localnet";
+import { formatSompi as formatSompi2 } from "@hardkas/core";
+async function runTxReceipt(input) {
+  const { txId, cwd } = input;
+  const receipt = await loadSimulatedReceipt(txId, cwd ? { cwd } : void 0);
+  const lines = [
+    "Transaction receipt",
+    "",
+    `Tx ID:     ${receipt.txId}`,
+    `Mode:      ${receipt.mode}`,
+    `Network:   ${receipt.networkId}`,
+    `From:      ${receipt.from.address}`,
+    `To:        ${receipt.to.address}`,
+    `Amount:    ${formatSompi2(BigInt(receipt.amountSompi))}`,
+    `Fee:       ${formatSompi2(BigInt(receipt.feeSompi))}`,
+    `Change:    ${receipt.changeSompi ? formatSompi2(BigInt(receipt.changeSompi)) : "none"}`,
+    `DAA score: ${receipt.daaScore}`,
+    `Created:   ${receipt.createdAt}`,
+    "",
+    "State:",
+    `  Spent UTXOs:   ${receipt.spentUtxoIds.length}`,
+    `  Created UTXOs: ${receipt.createdUtxoIds.length}`
+  ];
+  return {
+    receipt,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/commands/tx.ts
+function registerTxCommands(program) {
+  const tx = program.command("tx").description("L1 Transaction commands");
+  tx.command("profile <path>").description("Show detailed mass and fee breakdown for a transaction plan").action(async (path11) => {
+    try {
+      await runTxProfile({ path: path11 });
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  tx.command("plan").description("Build a transaction plan artifact").option("--from <accountOrAddress>", "Sender account name or address").option("--to <address>", "Recipient address").option("--amount <kas>", "Amount in KAS").option("--network <name>", "Kaspa network name", "simnet").option("--fee-rate <sompiPerMass>", "Fee rate in sompi per mass", "1").option("--url <url>", "RPC URL (optional override)").option("--out <path>", "Save plan as artifact JSON").option("--json", "Output as JSON", false).action(async (options) => {
+    try {
+      const { loadHardkasConfig: loadHardkasConfig3 } = await import("@hardkas/config");
+      const { writeArtifact: writeArtifact4, formatTxPlanArtifact } = await import("@hardkas/artifacts");
+      const loaded = await loadHardkasConfig3();
+      const artifact = await runTxPlan({
+        from: options.from || "alice",
+        to: options.to || "bob",
+        amount: options.amount || "1",
+        networkId: options.network,
+        feeRate: options.feeRate,
+        config: loaded.config,
+        ...options.url ? { url: options.url } : {}
+      });
+      if (options.out) await writeArtifact4(options.out, artifact);
+      if (options.json) console.log(JSON.stringify(artifact, bigIntReplacer, 2));
+      else {
+        console.log(formatTxPlanArtifact(artifact));
+        if (options.out) console.log(`
+Artifact saved to: ${options.out}`);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  tx.command("sign <planPath>").description("Sign a transaction plan artifact").option("--account <name>", "Account name to sign with").option("--out <path>", "Save signed artifact JSON").option("--allow-mainnet-signing", "Allow signing for mainnet", false).option("--json", "Output as JSON", false).action(async (planPath, options) => {
+    try {
+      const { readTxPlanArtifact, writeArtifact: writeArtifact4, formatSignedTxArtifact } = await import("@hardkas/artifacts");
+      const { loadHardkasConfig: loadHardkasConfig3 } = await import("@hardkas/config");
+      const planArtifact = await readTxPlanArtifact(planPath);
+      const loaded = await loadHardkasConfig3();
+      const signedArtifact = await runTxSign({
+        planArtifact,
+        ...options.account ? { accountName: options.account } : {},
+        config: loaded.config,
+        allowMainnetSigning: options.allowMainnetSigning
+      });
+      if (options.out) await writeArtifact4(options.out, signedArtifact);
+      if (options.json) console.log(JSON.stringify(signedArtifact, bigIntReplacer, 2));
+      else {
+        console.log(formatSignedTxArtifact(signedArtifact));
+        if (options.out) console.log(`
+Signed artifact saved to: ${options.out}`);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  tx.command("send [signedPath]").description("Broadcast a signed transaction or send directly (simulated)").option("--from <accountOrAddress>", "Sender (shortcut mode)").option("--to <address>", "Recipient (shortcut mode)").option("--amount <kas>", "Amount in KAS (shortcut mode)").option("--network <name>", "Network name", "simnet").option("--url <url>", "RPC URL (optional override)").option("--yes", "Confirm broadcast", false).option("--json", "Output as JSON", false).action(async (signedPath, options) => {
+    try {
+      const { loadHardkasConfig: loadHardkasConfig3 } = await import("@hardkas/config");
+      const loaded = await loadHardkasConfig3();
+      if (signedPath) {
+        const { readSignedTxArtifact } = await import("@hardkas/artifacts");
+        const signedArtifact = await readSignedTxArtifact(signedPath);
+        if (!options.yes && signedArtifact.networkId !== "simnet") {
+          console.log(`Transaction is for network: ${signedArtifact.networkId}`);
+          console.log("Run with --yes to broadcast.");
+          return;
+        }
+        const result = await runTxSend({
+          signedArtifact,
+          network: options.network,
+          config: loaded.config,
+          ...options.url ? { url: options.url } : {}
+        });
+        if (options.json) console.log(JSON.stringify(result, bigIntReplacer, 2));
+        else console.log(result.formatted);
+      } else if (options.from && options.to && options.amount) {
+        const result = await runTxFlow({
+          ...options,
+          amount: options.amount,
+          from: options.from,
+          to: options.to,
+          send: true,
+          feeRate: "1",
+          // Default fee rate for shortcut
+          config: loaded.config,
+          ...options.url ? { url: options.url } : {}
+        });
+        if (options.json) console.log(JSON.stringify(result, bigIntReplacer, 2));
+        else console.log(result.steps.send.artifact?.formatted || "Flow completed");
+      } else {
+        console.error("Provide a path to a signed artifact or use --from, --to, --amount.");
+        process.exitCode = 1;
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  tx.command("receipt <txId>").description("Show transaction receipt").option("--json", "Output as JSON", false).action(async (txId, options) => {
+    try {
+      const result = await runTxReceipt({ txId });
+      if (options.json) console.log(JSON.stringify(result.receipt, bigIntReplacer, 2));
+      else console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  tx.command("verify <path>").description("Perform deep semantic verification of a transaction plan").option("--json", "Output as JSON", false).action(async (path11, options) => {
+    const { runTxVerify } = await import("./tx-verify-runner-GPPVBQIF.js");
+    await runTxVerify({ path: path11, ...options });
+  });
+  tx.command("trace <txId>").description("Reconstruct the full operational trace of a transaction").action(async (txId) => {
+    const { UI: UI2 } = await import("./ui-DXULTF7Q.js");
+    UI2.error("Tracing is temporarily disabled while the query API stabilizes.");
+    process.exitCode = 1;
+  });
+}
+
+// src/runners/artifact-verify-runner.ts
+import { verifyArtifactIntegrity, verifyArtifactSemantics } from "@hardkas/artifacts";
+import path4 from "path";
+import fs3 from "fs";
+async function runArtifactVerify(options) {
+  const absolutePath = path4.resolve(process.cwd(), options.path);
+  if (!fs3.existsSync(absolutePath)) {
+    UI.error(`Path not found: ${options.path}`);
+    process.exitCode = 1;
+    return;
+  }
+  const stats = fs3.statSync(absolutePath);
+  const isDir = stats.isDirectory();
+  if (isDir) {
+    if (options.recursive) {
+      return runRecursiveVerify(absolutePath, options);
+    } else {
+      UI.error(`${options.path} is a directory. Use --recursive to verify all artifacts within it.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  let result = await verifyArtifactIntegrity(absolutePath);
+  const artifact = JSON.parse(fs3.readFileSync(absolutePath, "utf-8"));
+  const semanticResult = verifyArtifactSemantics(artifact, { strict: options.strict ?? false });
+  result.issues.push(...semanticResult.issues);
+  result.errors.push(...semanticResult.errors);
+  result.ok = result.ok && semanticResult.ok;
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  UI.header(`Artifact Verification: ${path4.basename(options.path)}`);
+  if (result.ok) {
+    UI.success("VERIFICATION SUCCESSFUL");
+    console.log(`  Type:    ${result.artifactType}`);
+    console.log(`  Version: ${result.version}`);
+    console.log(`  Hash:    ${result.actualHash}`);
+    if (options.strict) {
+      console.log(`
+Operational Audit (STRICT):`);
+      const feeAudit = verifyArtifactSemantics(artifact, { strict: true });
+      if (feeAudit.ok) {
+        UI.success("  \u2713 Economic invariants verified.");
+      } else {
+        UI.error("  \u2717 Economic invariants VIOLATED.");
+      }
+    }
+  } else {
+    UI.error("VERIFICATION FAILED");
+    renderErrors(result);
+    process.exitCode = 1;
+  }
+  return result;
+}
+async function runRecursiveVerify(dir, options) {
+  const files = getAllJsonFiles(dir);
+  UI.header(`Recursive Verification: ${path4.basename(dir)}`);
+  console.log(`Auditing ${files.length} artifact(s)...
+`);
+  let successCount = 0;
+  let failCount = 0;
+  for (const file of files) {
+    const relativePath = path4.relative(dir, file);
+    const result = await verifyArtifactIntegrity(file);
+    const artifact = JSON.parse(fs3.readFileSync(file, "utf-8"));
+    const semanticResult = verifyArtifactSemantics(artifact, { strict: options.strict ?? false });
+    result.issues.push(...semanticResult.issues);
+    result.errors.push(...semanticResult.errors);
+    result.ok = result.ok && semanticResult.ok;
+    if (result.ok) {
+      console.log(`  \u2713 ${relativePath.padEnd(40)} [MATCH]`);
+      successCount++;
+    } else {
+      console.log(`  \u2717 ${relativePath.padEnd(40)} [FAIL]`);
+      result.issues.forEach((issue) => {
+        const prefix = issue.severity === "critical" ? "[!!!]" : issue.severity === "error" ? "[!]" : "[?]";
+        console.log(`      ${prefix} [${issue.code}] ${issue.message}`);
+      });
+      failCount++;
+    }
+  }
+  console.log("\n" + "\u2550".repeat(50));
+  if (failCount === 0) {
+    UI.success(`Audit Complete: All ${successCount} artifacts verified.`);
+  } else {
+    UI.error(`Audit Failed: ${failCount} artifact(s) corrupted or invalid.`);
+    process.exitCode = 1;
+  }
+}
+function getAllJsonFiles(dirPath, arrayOfFiles = []) {
+  const files = fs3.readdirSync(dirPath);
+  files.forEach((file) => {
+    const fullPath = path4.join(dirPath, file);
+    if (fs3.statSync(fullPath).isDirectory()) {
+      arrayOfFiles = getAllJsonFiles(fullPath, arrayOfFiles);
+    } else if (file.endsWith(".json")) {
+      arrayOfFiles.push(fullPath);
+    }
+  });
+  return arrayOfFiles;
+}
+function renderErrors(result) {
+  if (result.artifactType) console.log(`  Type:    ${result.artifactType}`);
+  if (result.version) console.log(`  Version: ${result.version}`);
+  if (result.expectedHash || result.actualHash) {
+    console.log(`  Expected Hash: ${result.expectedHash || "None"}`);
+    console.log(`  Actual Hash:   ${result.actualHash || "N/A"}`);
+  }
+  console.log("\nIssues:");
+  result.issues.forEach((issue) => {
+    const prefix = issue.severity === "critical" ? "CRITICAL: " : issue.severity === "error" ? "ERROR:    " : "WARNING:  ";
+    console.log(`- ${prefix}[${issue.code}] ${issue.message}`);
+  });
+}
+
+// src/runners/artifact-explain-runner.ts
+import { explainArtifact } from "@hardkas/artifacts";
+import fs4 from "fs";
+import path5 from "path";
+import { formatSompi as formatSompi3 } from "@hardkas/core";
+async function runArtifactExplain(options) {
+  const absolutePath = path5.resolve(process.cwd(), options.path);
+  if (!fs4.existsSync(absolutePath)) {
+    UI.error(`File not found: ${options.path}`);
+    process.exitCode = 1;
+    return;
+  }
+  const rawArtifact = JSON.parse(fs4.readFileSync(absolutePath, "utf-8"));
+  const explanation = await explainArtifact(rawArtifact);
+  UI.header(`Operational Audit: ${path5.basename(options.path)}`);
+  console.log("\u250C\u2500\u2500 SUMMARY \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log(`\u2502 TYPE:      ${explanation.summary.type.padEnd(48)} \u2502`);
+  console.log(`\u2502 VERSION:   ${explanation.summary.version.padEnd(48)} \u2502`);
+  console.log(`\u2502 NETWORK:   ${explanation.summary.network.padEnd(48)} \u2502`);
+  console.log(`\u2502 MODE:      ${explanation.summary.mode.toUpperCase().padEnd(48)} \u2502`);
+  console.log(`\u2502 CREATED:   ${explanation.summary.createdAt.padEnd(48)} \u2502`);
+  console.log(`\u2502 STATUS:    ${explanation.summary.status.toUpperCase().padEnd(48)} \u2502`);
+  console.log("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("\n[ IDENTITY & LINEAGE ]");
+  console.log(`  ArtifactId: ${explanation.identity.artifactId}`);
+  console.log(`  Hash:       ${explanation.identity.contentHash}`);
+  if (explanation.identity.lineageId) {
+    console.log(`  LineageId:  ${explanation.identity.lineageId}`);
+    console.log(`  RootId:     ${explanation.identity.rootArtifactId}`);
+    console.log(`  ParentId:   ${explanation.identity.parentArtifactId || "None (Root)"}`);
+  }
+  if (explanation.economics) {
+    console.log("\n[ ECONOMIC AUDIT ]");
+    if (explanation.economics.ok) {
+      UI.success("  \u2713 Economic invariants verified.");
+    } else {
+      UI.error("  \u2717 Economic invariants VIOLATED.");
+    }
+    console.log(`
+  Mass:`);
+    console.log(`    Reported:   ${explanation.economics.mass.reported}`);
+    console.log(`    Recomputed: ${explanation.economics.mass.recomputed}`);
+    console.log(`
+  Fees:`);
+    console.log(`    Reported:   ${formatSompi3(explanation.economics.fee.reported)}`);
+    console.log(`    Recomputed: ${formatSompi3(explanation.economics.fee.recomputed)}`);
+    console.log(`    Rate:       ${explanation.economics.fee.rate} sompi/mass`);
+    if (explanation.economics.fee.delta !== 0n) {
+      const delta = explanation.economics.fee.delta;
+      const type = delta > 0n ? "Overpaid" : "Underpaid";
+      const absDelta = delta < 0n ? -delta : delta;
+      console.log(`    Delta:      ${formatSompi3(absDelta)} (${type})`);
+    }
+    console.log(`
+  Balance Sheet:`);
+    console.log(`    Total Inputs:  ${formatSompi3(explanation.economics.balance.inputs)}`);
+    console.log(`    Total Outputs: ${formatSompi3(explanation.economics.balance.outputs)}`);
+    if (explanation.economics.balance.change > 0n) {
+      console.log(`    Change:        ${formatSompi3(explanation.economics.balance.change)}`);
+    }
+    console.log(`    Implied Fee:   ${formatSompi3(explanation.economics.balance.impliedFee)}`);
+  }
+  console.log("\n[ SECURITY & INTEGRITY ]");
+  if (explanation.security.strictOk) {
+    UI.success("  \u2713 No critical integrity violations detected.");
+  } else {
+    UI.error("  \u2717 SECUIRTY WARNINGS DETECTED.");
+  }
+  if (explanation.security.issues.length > 0) {
+    explanation.security.issues.forEach((issue) => {
+      const prefix = issue.severity === "critical" ? "CRITICAL" : issue.severity === "error" ? "ERROR" : "WARNING";
+      console.log(`  \u2022 [${prefix}] [${issue.code}] ${issue.message}`);
+    });
+  }
+  UI.divider();
+}
+
+// src/commands/artifact.ts
+function registerArtifactCommands(program) {
+  const artifactCmd = program.command("artifact").description("Manage HardKAS artifacts");
+  artifactCmd.command("verify <path>").description("Verify an artifact's integrity and schema").option("--json", "Output results as JSON", false).option("--recursive", "Recursively verify all artifacts in a directory", false).option("--strict", "Perform deep semantic and operational safety verification", false).action(async (path11, options) => {
+    try {
+      await runArtifactVerify({ path: path11, ...options });
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  artifactCmd.command("explain <path>").description("Provide a human-readable operational summary of an artifact").action(async (path11) => {
+    try {
+      await runArtifactExplain({ path: path11 });
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  artifactCmd.command("lineage <path>").description("Show the provenance and operational history of an artifact").action(async (path11) => {
+    try {
+      const { runArtifactLineage } = await import("./artifact-lineage-runner-EPT6ABS2.js");
+      await runArtifactLineage({ path: path11 });
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/replay.ts
+function registerReplayCommands(program) {
+  const replayCmd = program.command("replay").description("Manage HardKAS transaction replays");
+  replayCmd.command("verify <path>").description("Verify replay invariants for a directory of artifacts").action(async (path11) => {
+    const { runReplayVerify } = await import("./replay-verify-runner-WBK2FCWC.js");
+    await runReplayVerify({ path: path11 });
+  });
+}
+
+// src/commands/snapshot.ts
+function registerSnapshotCommands(program) {
+  const snapshotCmd = program.command("snapshot").description("Manage HardKAS localnet snapshots");
+  snapshotCmd.command("verify <idOrName>").description("Verify the integrity of a snapshot").action(async (idOrName) => {
+    const { runSnapshotVerify } = await import("./snapshot-verify-runner-UYTXXQ7A.js");
+    await runSnapshotVerify({ idOrName });
+  });
+  snapshotCmd.command("restore <idOrName>").description("Restore localnet state from a snapshot").action(async (idOrName) => {
+    const { runSnapshotRestore } = await import("./snapshot-restore-runner-P26HDE74.js");
+    await runSnapshotRestore({ idOrName });
+  });
+}
+
+// src/runners/rpc-info-runner.ts
+import { KaspaJsonRpcClient } from "@hardkas/kaspa-rpc";
+async function runRpcInfo(options = {}) {
+  const client = new KaspaJsonRpcClient({ url: options.url || "http://127.0.0.1:18210" });
+  const info = await client.getServerInfo();
+  const url = options.url || "http://127.0.0.1:18210";
+  const lines = [
+    "Kaspa RPC info",
+    "",
+    `URL:      ${url}`,
+    `Network:  ${info.networkId}`,
+    `Synced:   ${info.isSynced ? "yes" : "no"}`,
+    `Version:  ${info.serverVersion || "unknown"}`
+  ];
+  return {
+    info,
+    url,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/runners/rpc-health-runner.ts
+import {
+  checkKaspaRpcHealth,
+  waitForKaspaRpcReady
+} from "@hardkas/kaspa-rpc";
+async function runRpcHealth(options) {
+  const start = Date.now();
+  let result;
+  if (options.wait) {
+    console.log(`Waiting for Kaspa RPC at ${options.url || "http://127.0.0.1:18210"} ...`);
+    result = await waitForKaspaRpcReady({
+      url: options.url,
+      maxWaitMs: (options.timeout || 60) * 1e3,
+      intervalMs: options.interval || 1e3
+    });
+  } else {
+    result = await checkKaspaRpcHealth({ url: options.url });
+  }
+  const durationMs = Date.now() - start;
+  let formatted = "";
+  if (result.ready) {
+    if (options.wait) {
+      formatted += `Ready after ${Math.round(durationMs / 100) / 10}s
+
+`;
+    }
+    formatted += [
+      "Kaspa RPC health",
+      "",
+      `URL:      ${result.endpoint}`,
+      `Status:   ready`,
+      `Latency:  ${result.latencyMs}ms`,
+      `Network:  ${result.networkId}`,
+      `DAA:      ${result.virtualDaaScore}`,
+      `Version:  ${result.serverVersion || "unknown"}`,
+      `Synced:   ${result.isSynced ? "yes" : "no"}`
+    ].join("\n");
+  } else {
+    if (options.wait) {
+      formatted += `RPC not ready after ${options.timeout || 60}s
+
+`;
+    }
+    formatted += [
+      "Kaspa RPC health",
+      "",
+      `URL:      ${result.endpoint}`,
+      `Status:   not ready`,
+      `Error:    ${result.error}`,
+      "",
+      "Suggestion:",
+      "  hardkas node status",
+      "  hardkas node logs --tail 50"
+    ].join("\n");
+  }
+  return {
+    result,
+    formatted,
+    durationMs
+  };
+}
+
+// src/runners/rpc-dag-runner.ts
+import { KaspaJsonRpcClient as KaspaJsonRpcClient2 } from "@hardkas/kaspa-rpc";
+async function runRpcDag(options = {}) {
+  const client = new KaspaJsonRpcClient2({ url: options.url || "http://127.0.0.1:18210" });
+  const dag = await client.getBlockDagInfo();
+  const lines = [
+    "Kaspa DAG info",
+    "",
+    `Network:        ${dag.networkId}`,
+    `Virtual DAA:    ${dag.virtualDaaScore?.toString() || "unknown"}`,
+    `Tips:           ${dag.tipHashes?.length || 0}`
+  ];
+  if (dag.tipHashes && dag.tipHashes.length > 0) {
+    lines.push("");
+    lines.push("Tips:");
+    dag.tipHashes.slice(0, 5).forEach((hash) => lines.push(`  - ${hash}`));
+    if (dag.tipHashes.length > 5) {
+      lines.push(`  ... and ${dag.tipHashes.length - 5} more`);
+    }
+  }
+  return {
+    dag,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/runners/rpc-utxos-runner.ts
+import { KaspaJsonRpcClient as KaspaJsonRpcClient3 } from "@hardkas/kaspa-rpc";
+import { formatSompi as formatSompi4 } from "@hardkas/core";
+async function runRpcUtxos(options) {
+  const client = new KaspaJsonRpcClient3({ url: options.url || "http://127.0.0.1:18210" });
+  const utxos = await client.getUtxosByAddress(options.address);
+  const lines = [
+    `Kaspa UTXOs for ${options.address}`,
+    "",
+    `Found: ${utxos.length} UTXO(s)`
+  ];
+  if (utxos.length > 0) {
+    lines.push("");
+    lines.push("ID                                      | Amount       | DAA Score");
+    lines.push("-".repeat(75));
+    utxos.forEach((u) => {
+      const id = `${u.outpoint.transactionId}:${u.outpoint.index}`.padEnd(40);
+      const amount = formatSompi4(u.amountSompi).padStart(12);
+      const score = (u.blockDaaScore?.toString() || "unknown").padStart(10);
+      lines.push(`${id} | ${amount} | ${score}`);
+    });
+    const total = utxos.reduce((acc, u) => acc + u.amountSompi, 0n);
+    lines.push("-".repeat(75));
+    lines.push(`Total balance: ${formatSompi4(total)}`);
+  }
+  return {
+    utxos,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/runners/rpc-mempool-runner.ts
+import { KaspaJsonRpcClient as KaspaJsonRpcClient4 } from "@hardkas/kaspa-rpc";
+async function runRpcMempool(options) {
+  const client = new KaspaJsonRpcClient4({ url: options.url || "http://127.0.0.1:18210" });
+  const entry = await client.getMempoolEntry(options.txId);
+  const lines = [
+    `Kaspa Mempool status for ${options.txId}`,
+    ""
+  ];
+  if (entry) {
+    lines.push(`Status:   Found in mempool`);
+    if (entry.acceptedAt) {
+      lines.push(`Time:     ${entry.acceptedAt}`);
+    }
+  } else {
+    lines.push(`Status:   Not found in mempool`);
+    lines.push(`Note:     The transaction might be already confirmed or was never seen.`);
+  }
+  return {
+    entry,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/commands/rpc.ts
+function registerRpcCommands(program) {
+  const rpcCmd = program.command("rpc").description("Kaspa RPC diagnostics and queries");
+  rpcCmd.command("info").description("Show RPC connection info").action(async () => {
+    try {
+      await runRpcInfo();
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  rpcCmd.command("health").description("Check RPC health").action(async () => {
+    try {
+      await runRpcHealth({});
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  rpcCmd.command("doctor").description("Run comprehensive RPC diagnostics").option("--endpoints <urls...>", "Specific endpoints to audit").action(async (options) => {
+    const { runRpcDoctor } = await import("./rpc-doctor-runner-RKGKFGMM.js");
+    try {
+      await runRpcDoctor(options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  rpcCmd.command("dag").description("Show DAG information from node").action(async () => {
+    try {
+      await runRpcDag();
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  rpcCmd.command("utxos <address>").description("Show UTXOs for an address from node").action(async (address) => {
+    try {
+      await runRpcUtxos({ address });
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  rpcCmd.command("mempool [txId]").description("Show mempool status from node").action(async (txId) => {
+    try {
+      await runRpcMempool({ txId: txId || "all" });
+    } catch (e) {
+      handleError(e);
+    }
+  });
+}
+
+// src/commands/dag.ts
+function registerDagCommands(program) {
+  const dagCmd = program.command("dag").description("Simulate blockDAG operations (Localnet only)");
+  dagCmd.command("status").description("View current DAG status").action(async () => {
+    try {
+      const { runDagStatus } = await import("./dag-runners-BQAKJ6DM.js");
+      await runDagStatus();
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  dagCmd.command("simulate-reorg").description("Simulate a DAG reorg").option("--depth <n>", "Reorg depth", "1").action(async (options) => {
+    try {
+      const { runDagSimulateReorg } = await import("./dag-runners-BQAKJ6DM.js");
+      await runDagSimulateReorg({ depth: parseInt(options.depth) });
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/runners/accounts-real-init-runner.ts
+import {
+  loadRealAccountStore,
+  saveRealAccountStore,
+  createEmptyRealAccountStore,
+  getDefaultRealAccountsPath
+} from "@hardkas/accounts";
+async function runAccountsRealInit(options = {}) {
+  const filePath = getDefaultRealAccountsPath();
+  const existing = await loadRealAccountStore();
+  if (existing && !options.force) {
+    throw new Error(`Real account store already exists at ${filePath}. Use --force to overwrite.`);
+  }
+  const store = createEmptyRealAccountStore();
+  await saveRealAccountStore(store);
+  const lines = [
+    "Real dev account store initialized",
+    "",
+    `Path:    ${filePath}`,
+    `Network: ${store.networkId}`,
+    "",
+    "WARNING:",
+    "  Development keys only. Do not use on mainnet."
+  ];
+  return {
+    path: filePath,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/runners/accounts-real-generate-runner.ts
+import {
+  loadOrCreateRealAccountStore,
+  saveRealAccountStore as saveRealAccountStore2,
+  importRealDevAccount,
+  KaspaSdkKeyGenerator
+} from "@hardkas/accounts";
+async function runAccountsRealGenerate(options = {}) {
+  const generator = new KaspaSdkKeyGenerator(options.networkId ? { networkId: options.networkId } : {});
+  const count = options.count || 1;
+  let store = await loadOrCreateRealAccountStore();
+  const generatedAccounts = [];
+  for (let i = 0; i < count; i++) {
+    const name = count === 1 && options.name ? options.name : options.name ? `${options.name}${i + 1}` : `account${i}`;
+    const generated = await generator.generateAccount(options.networkId ? { networkId: options.networkId } : {});
+    store = importRealDevAccount(store, {
+      name,
+      address: generated.address,
+      ...generated.publicKey ? { publicKey: generated.publicKey } : {},
+      ...generated.privateKey ? { privateKey: generated.privateKey } : {}
+    });
+    generatedAccounts.push(store.accounts[store.accounts.length - 1]);
+  }
+  await saveRealAccountStore2(store);
+  const lines = [
+    `Generated ${count} real dev account(s)`,
+    "",
+    "WARNING: Development keys only. Do not use on mainnet.",
+    ""
+  ];
+  generatedAccounts.forEach((a) => {
+    lines.push(`Name:    ${a.name}`);
+    lines.push(`Address: ${a.address}`);
+    lines.push(`Private: yes (masked)`);
+    lines.push("");
+  });
+  return {
+    accounts: generatedAccounts,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/commands/accounts.ts
+function registerAccountsCommands(program) {
+  const accountsCmd = program.command("accounts").description("Manage HardKAS accounts");
+  accountsCmd.command("list").description("List available HardKAS accounts").option("--config <path>", "Path to config file").option("--json", "Output as JSON", false).action(async (options) => {
+    const { loadHardkasConfig: loadHardkasConfig3 } = await import("@hardkas/config");
+    const { listHardkasAccounts: listHardkasAccounts2, describeAccount } = await import("@hardkas/accounts");
+    try {
+      const loaded = await loadHardkasConfig3(options.config ? { configPath: options.config } : {});
+      const accounts = listHardkasAccounts2(loaded.config);
+      if (options.json) {
+        console.log(JSON.stringify(accounts.map((a) => describeAccount(a)), null, 2));
+        return;
+      }
+      console.log("HardKAS accounts");
+      console.log("");
+      for (const acc of accounts) {
+        const encrypted = acc.kind === "kaspa-private-key" && !acc.privateKeyEnv ? " (encrypted)" : "";
+        console.log(`${acc.name.padEnd(12)} ${acc.address?.padEnd(24)} (${acc.kind})${encrypted}`);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  const realAccountsCmd = accountsCmd.command("real").description("Persistent dev account store (L1)");
+  realAccountsCmd.command("init").description("Initialize real dev account store").option("--force", "Overwrite existing store", false).option("--json", "Output as JSON", false).action(async (options) => {
+    try {
+      const result = await runAccountsRealInit({ force: options.force });
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  realAccountsCmd.command("import").description("Import an account into the persistent store").option("--name <name>", "Account name").option("--address <address>", "Kaspa address").option("--private-key <hex>", "Private key (plaintext, discouraged)").option("--encrypted", "Import as encrypted keystore (recommended)", false).option("--json", "Output as JSON", false).action(async (options) => {
+    try {
+      const { runAccountsKeystoreImport } = await import("./accounts-keystore-runners-CVRE6NVM.js");
+      const result = await runAccountsKeystoreImport(options);
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  realAccountsCmd.command("unlock <name>").description("Verify password for an encrypted account").action(async (name) => {
+    try {
+      const { runAccountsKeystoreUnlock } = await import("./accounts-keystore-runners-CVRE6NVM.js");
+      await runAccountsKeystoreUnlock({ name });
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  realAccountsCmd.command("lock <name>").description("Lock an account (clear session)").action(async (name) => {
+    try {
+      console.log(`Account '${name}' is now locked. (Session cleared)`);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  realAccountsCmd.command("change-password <name>").description("Change password for an encrypted account").action(async (name) => {
+    try {
+      const { runAccountsKeystoreChangePassword } = await import("./accounts-keystore-runners-CVRE6NVM.js");
+      await runAccountsKeystoreChangePassword({ name });
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  realAccountsCmd.command("generate").description("Generate new real dev account(s) using Kaspa SDK").option("--name <name>", "Base name for account(s)").option("--count <number>", "Number of accounts to generate", "1").option("--network <network>", "Kaspa network (simnet, testnet-10, mainnet)", "simnet").option("--json", "Output as JSON", false).action(async (options) => {
+    try {
+      const result = await runAccountsRealGenerate({
+        ...options.name ? { name: options.name } : {},
+        count: parseInt(options.count, 10),
+        networkId: options.network
+      });
+      if (options.json) console.log(JSON.stringify(result.accounts, null, 2));
+      else console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/runners/l2-networks-runner.ts
+import { listL2Profiles } from "@hardkas/l2";
+async function runL2Networks(options = {}) {
+  const profiles = listL2Profiles();
+  if (options.json) {
+    console.log(JSON.stringify(profiles, null, 2));
+    return;
+  }
+  console.log("L2 networks");
+  console.log("");
+  if (profiles.length === 0) {
+    console.log("No L2 profiles found.");
+    return;
+  }
+  for (const p of profiles) {
+    const bridge = p.security.bridgePhase;
+    const exit = p.security.trustlessExit ? "yes" : "no";
+    console.log(`${p.name.padEnd(8)} ${p.displayName.padEnd(8)} ${p.type.padEnd(18)} gas: ${p.gasToken.padEnd(8)} bridge: ${bridge.padEnd(8)} trustless exit: ${exit}`);
+  }
+}
+
+// src/runners/l2-profile-show-runner.ts
+import { getL2Profile } from "@hardkas/l2";
+async function runL2ProfileShow(options) {
+  const profile = getL2Profile(options.name);
+  if (!profile) {
+    throw new Error(`L2 profile '${options.name}' not found.`);
+  }
+  if (options.json) {
+    console.log(JSON.stringify(profile, null, 2));
+    return;
+  }
+  console.log("L2 profile");
+  console.log("");
+  console.log(`Name:        ${profile.name}`);
+  console.log(`Display:     ${profile.displayName}`);
+  console.log(`Type:        ${profile.type}`);
+  console.log(`Settlement:  ${profile.settlementLayer === "kaspa" ? "Kaspa L1" : profile.settlementLayer}`);
+  console.log(`Execution:   ${profile.executionLayer === "evm" ? "EVM L2" : profile.executionLayer}`);
+  console.log(`Gas token:   ${profile.gasToken}`);
+  console.log(`Bridge:      ${profile.security.bridgePhase}`);
+  console.log(`Trustless exit: ${profile.security.trustlessExit ? "yes" : "no"}`);
+  console.log(`Risk:        ${profile.security.riskProfile}`);
+  if (profile.security.notes && profile.security.notes.length > 0) {
+    console.log("");
+    console.log("Notes:");
+    for (const note of profile.security.notes) {
+      console.log(`  - ${note}`);
+    }
+  }
+}
+
+// src/runners/l2-profile-validate-runner.ts
+import { getL2Profile as getL2Profile2, validateL2Profile } from "@hardkas/l2";
+async function runL2ProfileValidate(options) {
+  const profile = getL2Profile2(options.name);
+  if (!profile) {
+    throw new Error(`L2 profile '${options.name}' not found.`);
+  }
+  const result = validateL2Profile(profile);
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.ok) {
+    console.log(`L2 profile '${options.name}' is VALID.`);
+  } else {
+    console.log(`L2 profile '${options.name}' is INVALID:`);
+    for (const err of result.errors) {
+      console.log(`  - ${err}`);
+    }
+    process.exit(1);
+  }
+}
+
+// src/runners/l2-tx-runners.ts
+import fs5 from "fs/promises";
+import path6 from "path";
+import {
+  getL2Profile as getL2Profile3,
+  EvmJsonRpcClient,
+  toHexQuantity,
+  normalizeEvmTransactionReceipt
+} from "@hardkas/l2";
+import {
+  assertValidIgraTxPlanArtifact,
+  assertValidIgraSignedTxArtifact,
+  writeArtifact as writeArtifact2,
+  readArtifact as readArtifact2,
+  HARDKAS_VERSION as HARDKAS_VERSION2,
+  ARTIFACT_SCHEMAS as ARTIFACT_SCHEMAS2,
+  createIgraPlanId,
+  createIgraSignedId,
+  assertValidIgraTxReceiptArtifact,
+  listIgraTxReceiptArtifacts,
+  loadIgraTxReceiptArtifact
+} from "@hardkas/artifacts";
+import {
+  loadRealAccountStore as loadRealAccountStore2,
+  resolveRealAccountOrAddress
+} from "@hardkas/accounts";
+async function runL2TxBuild(options) {
+  const networkName = options.network ?? "igra";
+  const profile = getL2Profile3(networkName);
+  if (!profile) {
+    throw new Error(`L2 profile '${networkName}' not found.`);
+  }
+  const rpcUrl = options.url ?? profile.rpcUrl;
+  if (!rpcUrl) {
+    throw new Error(`No L2 RPC URL configured for network '${networkName}'. Pass --url <rpcUrl>.`);
+  }
+  const client = new EvmJsonRpcClient({ url: rpcUrl });
+  if (options.from) assertEvmAddress(options.from, "from");
+  if (!options.to) {
+    throw new Error("Missing 'to' address. For this phase, 'to' is required.");
+  }
+  assertEvmAddress(options.to, "to");
+  if (options.data) assertHexData(options.data, "data");
+  const chainId = await client.getChainId();
+  let nonce = options.nonce;
+  if (!nonce && options.from) {
+    const n = await client.getTransactionCount(options.from, "latest");
+    nonce = n.toString();
+  }
+  let gasPrice = options.gasPrice;
+  if (!gasPrice) {
+    const gp = await client.getGasPriceWei();
+    gasPrice = gp.toString();
+  }
+  const request = {
+    ...options.from ? { from: options.from } : {},
+    to: options.to,
+    data: options.data ?? "0x",
+    value: options.value ? toHexQuantity(options.value) : "0x0"
+  };
+  let gasLimit = options.gasLimit;
+  if (!gasLimit) {
+    const g = await client.estimateGas(request, "latest");
+    gasLimit = g.toString();
+  }
+  const estimatedFeeWei = (BigInt(gasLimit) * BigInt(gasPrice)).toString();
+  const planId = createIgraPlanId();
+  const artifact = {
+    schema: ARTIFACT_SCHEMAS2.IGRA_TX_PLAN,
+    hardkasVersion: HARDKAS_VERSION2,
+    networkId: profile.name,
+    mode: "l2-rpc",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    planId,
+    l2Network: profile.name,
+    chainId,
+    request: {
+      ...options.from ? { from: options.from } : {},
+      to: options.to,
+      data: options.data ?? "0x",
+      valueWei: options.value ?? "0",
+      gasLimit,
+      gasPriceWei: gasPrice,
+      ...nonce ? { nonce } : {}
+    },
+    estimatedGas: gasLimit,
+    estimatedFeeWei,
+    status: "built"
+  };
+  assertValidIgraTxPlanArtifact(artifact);
+  const outDir = options.outDir || "plans";
+  const sanitizedDir = path6.normalize(outDir).replace(/^(\.\.[\/\\])+/, "");
+  await fs5.mkdir(sanitizedDir, { recursive: true });
+  const artifactPath = path6.join(sanitizedDir, `${planId}.igra.plan.json`);
+  await writeArtifact2(artifactPath, artifact);
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: profile.name,
+      l2Network: networkName,
+      chainId,
+      planId,
+      artifactPath,
+      artifact
+    }, null, 2));
+    return;
+  }
+  console.log(`${profile.displayName} L2 transaction plan built`);
+  console.log("");
+  console.log(`Plan ID:    ${planId}`);
+  console.log(`Network:    ${networkName}`);
+  console.log(`Chain ID:   ${chainId}`);
+  console.log(`Mode:       l2-rpc`);
+  if (options.from) console.log(`From:       ${options.from}`);
+  console.log(`To:         ${options.to}`);
+  console.log(`Value:      ${options.value ?? "0"} wei`);
+  console.log(`Gas limit:  ${gasLimit}`);
+  console.log(`Gas price:  ${gasPrice} wei`);
+  console.log(`Est. fee:   ${estimatedFeeWei} wei`);
+  if (nonce) console.log(`Nonce:      ${nonce}`);
+  console.log("");
+  console.log("Artifact:");
+  console.log(`  ${artifactPath}`);
+  console.log("");
+  console.log("Next:");
+  console.log(`  hardkas l2 tx sign ${artifactPath} --account <name>`);
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is an Igra L2 EVM transaction plan, not a Kaspa L1 UTXO transaction.");
+}
+async function runL2TxSign(options) {
+  const planData = await readArtifact2(options.planPath);
+  assertValidIgraTxPlanArtifact(planData);
+  const plan = planData;
+  if (plan.schema !== ARTIFACT_SCHEMAS2.IGRA_TX_PLAN) {
+    throw new Error(`Invalid plan schema: ${plan.schema}`);
+  }
+  if (plan.mode !== "l2-rpc") {
+    throw new Error(`Invalid plan mode: ${plan.mode} (expected 'l2-rpc')`);
+  }
+  if (plan.status !== "built") {
+    throw new Error(`Invalid plan status: ${plan.status} (expected 'built')`);
+  }
+  let accountInfo;
+  if (options.account) {
+    const store = await loadRealAccountStore2();
+    const accountData = resolveRealAccountOrAddress(store, options.account);
+    if (plan.request.from && plan.request.from.toLowerCase() !== accountData.address.toLowerCase()) {
+      throw new Error(`Account address mismatch: plan specifies '${plan.request.from}' but resolved account '${accountData.name ?? accountData.address}' is '${accountData.address}'`);
+    }
+    accountInfo = {
+      name: accountData.name ?? void 0,
+      address: accountData.address,
+      privateKey: accountData.privateKey ?? void 0
+    };
+  }
+  const { ViemIgraTxSigner } = await import("@hardkas/l2");
+  const signer = options.signerOverride ?? new ViemIgraTxSigner();
+  let result;
+  try {
+    result = await signer.sign({
+      plan,
+      account: accountInfo
+    });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (msg.includes("not configured yet") || msg.includes("dependency (viem) is not installed")) {
+      console.log("");
+      console.log("Igra L2 signing is not available");
+      console.log("");
+      console.log("Reason:");
+      console.log(`  ${msg}`);
+      console.log("");
+      console.log("Suggestion:");
+      if (msg.includes("viem")) {
+        console.log("  Run 'pnpm add viem' in your project or configure an EVM signer adapter.");
+      } else {
+        console.log("  Configure an EVM-compatible signer adapter in a future phase.");
+      }
+      console.log("  No artifact was written.");
+      process.exit(1);
+    }
+    throw e;
+  }
+  const signedId = createIgraSignedId();
+  const artifact = {
+    schema: ARTIFACT_SCHEMAS2.IGRA_SIGNED_TX,
+    hardkasVersion: HARDKAS_VERSION2,
+    networkId: plan.networkId,
+    mode: "l2-rpc",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    signedId,
+    sourcePlanId: plan.planId,
+    sourcePlanPath: options.planPath,
+    l2Network: plan.l2Network,
+    chainId: plan.chainId,
+    rawTransaction: result.rawTransaction,
+    txHash: result.txHash || "unknown",
+    status: "signed"
+  };
+  assertValidIgraSignedTxArtifact(artifact);
+  const outDir = options.outDir || "signed";
+  const sanitizedDir = path6.normalize(outDir).replace(/^(\.\.[\/\\])+/, "");
+  await fs5.mkdir(sanitizedDir, { recursive: true });
+  const artifactPath = path6.join(sanitizedDir, `${signedId}.igra.signed.json`);
+  await writeArtifact2(artifactPath, artifact);
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: plan.networkId,
+      l2Network: plan.l2Network,
+      chainId: plan.chainId,
+      signedId,
+      artifactPath,
+      artifact
+    }, null, 2));
+    return;
+  }
+  console.log("Igra L2 transaction signed");
+  console.log("");
+  console.log(`Signed ID: ${signedId}`);
+  console.log(`Source:    ${options.planPath}`);
+  console.log(`Network:   ${plan.networkId}`);
+  console.log(`Chain ID:  ${plan.chainId}`);
+  if (plan.request.from) console.log(`From:      ${plan.request.from}`);
+  console.log(`To:        ${plan.request.to}`);
+  console.log(`Value:     ${plan.request.valueWei} wei`);
+  console.log("");
+  console.log("Artifact:");
+  console.log(`  ${artifactPath}`);
+  console.log("");
+  console.log("Next:");
+  console.log("  L2 transaction sending is not implemented yet.");
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is an Igra L2 EVM signed transaction, not a Kaspa L1 UTXO transaction.");
+}
+async function runL2TxSend(options) {
+  const artifactData = await readArtifact2(options.signedPath);
+  assertValidIgraSignedTxArtifact(artifactData);
+  const artifact = artifactData;
+  if (artifact.schema !== ARTIFACT_SCHEMAS2.IGRA_SIGNED_TX) {
+    throw new Error(`Invalid signed artifact schema: ${artifact.schema}`);
+  }
+  if (artifact.mode !== "l2-rpc") {
+    throw new Error(`Invalid artifact mode: ${artifact.mode} (expected 'l2-rpc')`);
+  }
+  if (artifact.status !== "signed") {
+    throw new Error(`Invalid artifact status: ${artifact.status} (expected 'signed')`);
+  }
+  if (!options.yes) {
+    console.log("");
+    console.log("Refusing to submit Igra L2 transaction without --yes.");
+    console.log("");
+    console.log("Reason:");
+    console.log("  This operation broadcasts a signed L2 transaction.");
+    console.log("");
+    console.log("Use:");
+    console.log(`  hardkas l2 tx send ${options.signedPath} --yes`);
+    process.exit(1);
+  }
+  const networkName = options.network ?? artifact.l2Network ?? "igra";
+  const profile = getL2Profile3(networkName);
+  if (!profile) {
+    throw new Error(`L2 profile '${networkName}' not found.`);
+  }
+  const isMainnet = networkName === "mainnet" || profile.name.includes("mainnet") || artifact.networkId === "mainnet" || artifact.chainId === 1;
+  if (isMainnet) {
+    throw new Error("L2 mainnet broadcast is disabled in HardKAS v0.2-alpha.");
+  }
+  const rpcUrl = options.url ?? profile.rpcUrl;
+  if (!rpcUrl) {
+    throw new Error(`No L2 RPC URL configured for network '${networkName}'. Pass --url <rpcUrl>.`);
+  }
+  const client = new EvmJsonRpcClient({ url: rpcUrl });
+  const remoteChainId = await client.getChainId();
+  if (remoteChainId !== artifact.chainId) {
+    console.log("");
+    console.log("Refusing to submit Igra L2 transaction: signed artifact chainId does not match RPC endpoint.");
+    console.log("");
+    console.log(`Artifact chainId: ${artifact.chainId}`);
+    console.log(`RPC chainId:      ${remoteChainId}`);
+    console.log("");
+    console.log("Suggestion:");
+    console.log("  Check --url and --network.");
+    process.exit(1);
+  }
+  const txHash = await client.sendRawTransaction(artifact.rawTransaction);
+  const receipt = {
+    schema: ARTIFACT_SCHEMAS2.IGRA_TX_RECEIPT,
+    hardkasVersion: HARDKAS_VERSION2,
+    networkId: artifact.networkId,
+    mode: "l2-rpc",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    txHash,
+    sourceSignedId: artifact.signedId,
+    sourceSignedPath: options.signedPath,
+    l2Network: artifact.l2Network,
+    chainId: artifact.chainId,
+    rpcUrl,
+    status: "submitted"
+  };
+  assertValidIgraTxReceiptArtifact(receipt);
+  const receiptDir = path6.join(".hardkas", "l2-receipts");
+  await fs5.mkdir(receiptDir, { recursive: true });
+  const receiptPath = path6.join(receiptDir, `${txHash}.igra.receipt.json`);
+  await writeArtifact2(receiptPath, receipt);
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: artifact.networkId,
+      l2Network: networkName,
+      chainId: artifact.chainId,
+      rpcUrl,
+      txHash,
+      artifactPath: options.signedPath,
+      receiptPath,
+      receipt
+    }, (key, value) => typeof value === "bigint" ? value.toString() : value, 2));
+    return;
+  }
+  console.log("Igra L2 transaction submitted");
+  console.log("");
+  console.log(`Tx hash:   ${txHash}`);
+  console.log(`Network:   ${networkName}`);
+  console.log(`Chain ID:  ${artifact.chainId}`);
+  console.log(`Mode:      l2-rpc`);
+  console.log(`Source:    ${options.signedPath}`);
+  console.log(`RPC:       ${rpcUrl}`);
+  console.log("");
+  console.log("Receipt:");
+  console.log(`  ${receiptPath}`);
+  console.log("");
+  console.log("Next:");
+  console.log("  Check receipt:");
+  console.log(`    hardkas l2 tx receipt ${txHash} --network ${networkName}`);
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is an Igra L2 EVM transaction, not a Kaspa L1 UTXO transaction.");
+}
+async function runL2TxReceipt(options) {
+  let localReceipt;
+  try {
+    localReceipt = await loadIgraTxReceiptArtifact(options.txHash);
+  } catch (e) {
+  }
+  const networkName = options.network ?? localReceipt?.l2Network ?? "igra";
+  const profile = getL2Profile3(networkName);
+  const rpcUrl = options.url ?? profile?.rpcUrl;
+  let remoteReceipt = null;
+  if (rpcUrl) {
+    const client = new EvmJsonRpcClient({ url: rpcUrl });
+    const raw = await client.getTransactionReceipt(options.txHash);
+    remoteReceipt = normalizeEvmTransactionReceipt(raw);
+  }
+  if (!localReceipt && !remoteReceipt) {
+    throw new Error(`Receipt not found for tx ${options.txHash} locally or via RPC.`);
+  }
+  const status = remoteReceipt?.status ?? (localReceipt ? "submitted" : "pending");
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: localReceipt?.networkId ?? "igra",
+      l2Network: networkName,
+      chainId: localReceipt?.chainId,
+      rpcUrl,
+      txHash: options.txHash,
+      status,
+      local: localReceipt,
+      remote: remoteReceipt
+    }, (key, value) => typeof value === "bigint" ? value.toString() : value, 2));
+    return;
+  }
+  console.log("Igra L2 transaction receipt");
+  console.log("");
+  console.log(`Tx hash:   ${options.txHash}`);
+  console.log(`Network:   ${networkName}`);
+  if (localReceipt) {
+    console.log(`Chain ID:  ${localReceipt.chainId}`);
+    console.log(`Local:     found`);
+    console.log(`Created:   ${localReceipt.createdAt}`);
+  } else {
+    console.log(`Local:     not found`);
+  }
+  if (remoteReceipt) {
+    console.log("");
+    console.log("Remote Status:");
+    console.log(`  Status:    ${remoteReceipt.status}`);
+    console.log(`  Block:     ${remoteReceipt.blockNumber ?? "unknown"}`);
+    console.log(`  Gas used:  ${remoteReceipt.gasUsed ?? "unknown"}`);
+  } else if (rpcUrl) {
+    console.log("");
+    console.log("Remote Status: pending or not found on this node");
+  }
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is an Igra L2 EVM transaction receipt, not a Kaspa L1 transaction.");
+}
+async function runL2TxStatus(options) {
+  const networkName = options.network ?? "igra";
+  const profile = getL2Profile3(networkName);
+  const rpcUrl = options.url ?? profile?.rpcUrl;
+  if (!rpcUrl) {
+    throw new Error(`No L2 RPC URL configured for network '${networkName}'. Pass --url <rpcUrl>.`);
+  }
+  const client = new EvmJsonRpcClient({ url: rpcUrl });
+  const raw = await client.getTransactionReceipt(options.txHash);
+  const remoteReceipt = normalizeEvmTransactionReceipt(raw);
+  const status = remoteReceipt?.status ?? "pending";
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: profile?.name ?? networkName,
+      l2Network: networkName,
+      rpcUrl,
+      txHash: options.txHash,
+      status,
+      remote: remoteReceipt
+    }, (key, value) => typeof value === "bigint" ? value.toString() : value, 2));
+    return;
+  }
+  console.log("Igra L2 transaction status");
+  console.log("");
+  console.log(`Tx hash:   ${options.txHash}`);
+  console.log(`Network:   ${networkName}`);
+  console.log(`Status:    ${status}`);
+  if (remoteReceipt) {
+    console.log(`Block:     ${remoteReceipt.blockNumber ?? "unknown"}`);
+    console.log(`Gas used:  ${remoteReceipt.gasUsed ?? "unknown"}`);
+  }
+}
+function assertEvmAddress(address, field) {
+  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
+    throw new Error(`Invalid EVM ${field}: must be a 0x-prefixed 40-character hex string.`);
+  }
+}
+function assertHexData(data, field) {
+  if (!/^0x([a-fA-F0-9]{2})*$/.test(data)) {
+    throw new Error(`Invalid hex ${field}: must be a 0x-prefixed even-length hex string.`);
+  }
+}
+
+// src/runners/l2-contract-runners.ts
+import fs6 from "fs/promises";
+import path7 from "path";
+import {
+  getL2Profile as getL2Profile4,
+  EvmJsonRpcClient as EvmJsonRpcClient2,
+  toHexQuantity as toHexQuantity2,
+  encodeConstructorArgs
+} from "@hardkas/l2";
+import {
+  assertValidIgraTxPlanArtifact as assertValidIgraTxPlanArtifact2,
+  writeArtifact as writeArtifact3,
+  HARDKAS_VERSION as HARDKAS_VERSION3,
+  ARTIFACT_SCHEMAS as ARTIFACT_SCHEMAS3,
+  createIgraDeployPlanId
+} from "@hardkas/artifacts";
+async function runL2ContractDeployPlan(options) {
+  const networkName = options.network ?? "igra";
+  const profile = getL2Profile4(networkName);
+  if (!profile) {
+    throw new Error(`L2 profile '${networkName}' not found.`);
+  }
+  const rpcUrl = options.url ?? profile.rpcUrl;
+  if (!rpcUrl) {
+    throw new Error(`No L2 RPC URL configured for network '${networkName}'. Pass --url <rpcUrl>.`);
+  }
+  const client = new EvmJsonRpcClient2({ url: rpcUrl });
+  assertEvmAddress2(options.from, "from");
+  if (!options.bytecode || options.bytecode === "0x") {
+    throw new Error("Missing or empty bytecode. Provide non-empty 0x-prefixed hex.");
+  }
+  assertHexData2(options.bytecode, "bytecode");
+  let data = options.bytecode;
+  if (typeof options.constructor === "string" && options.constructor) {
+    const argsArray = options.args ? options.args.split(",") : [];
+    data = encodeConstructorArgs(options.bytecode, options.constructor, argsArray);
+  }
+  const chainId = await client.getChainId();
+  let nonce = options.nonce;
+  if (!nonce) {
+    const n = await client.getTransactionCount(options.from, "latest");
+    nonce = n.toString();
+  }
+  let gasPrice = options.gasPrice;
+  if (!gasPrice) {
+    const gp = await client.getGasPriceWei();
+    gasPrice = gp.toString();
+  }
+  const request = {
+    from: options.from,
+    ...options.value ? { value: toHexQuantity2(options.value) } : { value: "0x0" },
+    data
+  };
+  let gasLimit = options.gasLimit;
+  if (!gasLimit) {
+    const g = await client.estimateGas(request, "latest");
+    gasLimit = g.toString();
+  }
+  const estimatedFeeWei = (BigInt(gasLimit) * BigInt(gasPrice)).toString();
+  const planId = createIgraDeployPlanId();
+  const artifact = {
+    schema: ARTIFACT_SCHEMAS3.IGRA_TX_PLAN,
+    hardkasVersion: HARDKAS_VERSION3,
+    networkId: profile.name,
+    mode: "l2-rpc",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    planId,
+    l2Network: profile.name,
+    chainId,
+    txType: "contract-deploy",
+    request: {
+      from: options.from,
+      data,
+      valueWei: options.value ?? "0",
+      gasLimit,
+      gasPriceWei: gasPrice,
+      ...nonce ? { nonce } : {}
+    },
+    estimatedGas: gasLimit,
+    estimatedFeeWei,
+    status: "built"
+  };
+  assertValidIgraTxPlanArtifact2(artifact);
+  const outDir = options.outDir || "plans";
+  const sanitizedDir = path7.normalize(outDir).replace(/^(\.\.[\/\\])+/, "");
+  await fs6.mkdir(sanitizedDir, { recursive: true });
+  const artifactPath = path7.join(sanitizedDir, `${planId}.igra.deploy.plan.json`);
+  await writeArtifact3(artifactPath, artifact);
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: profile.name,
+      l2Network: networkName,
+      chainId,
+      planId,
+      artifactPath,
+      artifact
+    }, null, 2));
+    return;
+  }
+  console.log(`Igra L2 contract deploy plan built`);
+  console.log("");
+  console.log(`Plan ID:    ${planId}`);
+  console.log(`Network:    ${networkName}`);
+  console.log(`Chain ID:   ${chainId}`);
+  console.log(`Mode:       l2-rpc`);
+  console.log(`From:       ${options.from}`);
+  console.log(`Type:       contract-deploy`);
+  console.log(`Value:      ${options.value ?? "0"} wei`);
+  console.log(`Gas limit:  ${gasLimit}`);
+  console.log(`Gas price:  ${gasPrice} wei`);
+  console.log(`Est. fee:   ${estimatedFeeWei} wei`);
+  if (nonce) console.log(`Nonce:      ${nonce}`);
+  console.log(`Bytecode:   ${options.bytecode.substring(0, 32)}...`);
+  console.log("");
+  console.log("Artifact:");
+  console.log(`  ${artifactPath}`);
+  console.log("");
+  console.log("Next:");
+  console.log("  Sign:");
+  console.log(`    hardkas l2 tx sign ${artifactPath} --account <account>`);
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is an Igra L2 EVM contract deployment plan, not a Kaspa L1 transaction.");
+}
+function assertEvmAddress2(address, field) {
+  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
+    throw new Error(`Invalid EVM ${field}: must be a 0x-prefixed 40-character hex string.`);
+  }
+}
+function assertHexData2(data, field) {
+  if (!/^0x([a-fA-F0-9]{2})*$/.test(data)) {
+    throw new Error(`Invalid hex ${field}: must be a 0x-prefixed even-length hex string.`);
+  }
+}
+
+// src/runners/l2-bridge-runners.ts
+import { getL2BridgeAssumptions } from "@hardkas/l2";
+async function runL2BridgeStatus(options) {
+  const networkName = options.network ?? "igra";
+  const assumptions = getL2BridgeAssumptions(networkName);
+  if (!assumptions) {
+    throw new Error(`No bridge assumptions found for network '${networkName}'.`);
+  }
+  if (options.json) {
+    console.log(JSON.stringify(assumptions, null, 2));
+    return;
+  }
+  console.log(`${capitalize(networkName)} bridge status`);
+  console.log("");
+  console.log(`Network:        ${assumptions.l2Network}`);
+  console.log(`Bridge phase:   ${assumptions.bridgePhase}`);
+  console.log(`Trustless exit: ${assumptions.trustlessExit ? "yes" : "no"}`);
+  console.log(`Risk:           ${assumptions.riskProfile}`);
+  console.log("");
+  console.log("Custody:");
+  console.log(`  ${assumptions.custodyModel}`);
+  console.log("");
+  console.log("Exit model:");
+  console.log(`  ${assumptions.exitModel}`);
+  console.log("");
+  console.log("Warnings:");
+  for (const note of assumptions.notes) {
+    console.log(`  - ${note}`);
+  }
+}
+async function runL2BridgeAssumptions(options) {
+  const networkName = options.network ?? "igra";
+  const assumptions = getL2BridgeAssumptions(networkName);
+  if (!assumptions) {
+    throw new Error(`No bridge assumptions found for network '${networkName}'.`);
+  }
+  if (options.json) {
+    console.log(JSON.stringify(assumptions, null, 2));
+    return;
+  }
+  console.log(`${capitalize(networkName)} bridge assumptions`);
+  console.log("");
+  console.log("Bridge security phases:");
+  console.log("  pre-ZK: stronger trust assumptions / non-trustless exit");
+  console.log("  MPC:    threshold committee trust assumptions");
+  console.log("  ZK:     validity-proof based trustless exit");
+  console.log("");
+  console.log("Current configured phase:");
+  console.log(`  ${assumptions.bridgePhase}`);
+  console.log("");
+  console.log("Trustless exit:");
+  console.log(`  ${assumptions.trustlessExit ? "yes" : "no"}`);
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// src/runners/l2-rpc-health-runner.ts
+import { getL2Profile as getL2Profile5, checkEvmRpcHealth, waitForEvmRpcReady } from "@hardkas/l2";
+async function runL2RpcHealth(options) {
+  const networkName = options.network ?? "igra";
+  const profile = getL2Profile5(networkName);
+  if (!profile) {
+    throw new Error(`L2 profile '${networkName}' not found.`);
+  }
+  const rpcUrl = options.url ?? profile.rpcUrl;
+  if (!rpcUrl) {
+    throw new Error(`No L2 RPC URL configured for network '${networkName}'. Pass --url <rpcUrl>.`);
+  }
+  const healthOptions = {
+    url: rpcUrl,
+    timeoutMs: (options.timeout ?? 60) * 1e3,
+    intervalMs: options.interval ?? 1e3,
+    maxWaitMs: (options.timeout ?? 60) * 1e3
+  };
+  const health = options.wait ? await waitForEvmRpcReady(healthOptions) : await checkEvmRpcHealth(healthOptions);
+  if (options.json) {
+    console.log(JSON.stringify(health, (key, value) => typeof value === "bigint" ? value.toString() : value, 2));
+    return;
+  }
+  console.log(`${profile.displayName} L2 RPC health`);
+  console.log("");
+  console.log(`Network:  ${networkName}`);
+  console.log(`URL:      ${health.url}`);
+  console.log(`Status:   ${health.ready ? "ready" : "not ready"}`);
+  if (health.ready) {
+    console.log(`Chain ID: ${health.chainId}`);
+    console.log(`Block:    ${health.blockNumber}`);
+    console.log(`Gas:      ${health.gasPriceWei} wei`);
+    if (health.latencyMs !== void 0) {
+      console.log(`Latency:  ${health.latencyMs}ms`);
+    }
+  }
+  if (health.error) {
+    console.log(`Error:    ${health.error}`);
+  }
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is L2 EVM state, not Kaspa L1 UTXO state.");
+  if (!health.ready) {
+    process.exitCode = 1;
+  }
+}
+
+// src/runners/l2-account-runners.ts
+import { getL2Profile as getL2Profile6, EvmJsonRpcClient as EvmJsonRpcClient3, formatWeiAsEtherLike } from "@hardkas/l2";
+async function getClient(options) {
+  const networkName = options.network ?? "igra";
+  const profile = getL2Profile6(networkName);
+  if (!profile) {
+    throw new Error(`L2 profile '${networkName}' not found.`);
+  }
+  const rpcUrl = options.url ?? profile.rpcUrl;
+  if (!rpcUrl) {
+    throw new Error(`No L2 RPC URL configured for network '${networkName}'. Pass --url <rpcUrl>.`);
+  }
+  return {
+    client: new EvmJsonRpcClient3({ url: rpcUrl }),
+    profile,
+    networkName
+  };
+}
+async function runL2Balance(address, options) {
+  const { client, profile, networkName } = await getClient(options);
+  const blockTag = options.block ?? "latest";
+  const balanceWei = await client.getBalanceWei(address, blockTag);
+  const balanceFormatted = formatWeiAsEtherLike(balanceWei, profile.gasToken, profile.nativeTokenDecimals);
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: profile.name,
+      l2Network: networkName,
+      chainId: profile.chainId,
+      rpcUrl: profile.rpcUrl,
+      address,
+      block: blockTag,
+      balanceWei: balanceWei.toString(),
+      balanceFormatted,
+      gasToken: profile.gasToken
+    }, null, 2));
+    return;
+  }
+  console.log(`${profile.displayName} L2 balance`);
+  console.log("");
+  console.log(`Network:  ${networkName}`);
+  console.log(`Address:  ${address}`);
+  console.log(`Block:    ${blockTag}`);
+  console.log(`Balance:  ${balanceFormatted}`);
+  console.log(`Wei:      ${balanceWei}`);
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is L2 EVM account state, not Kaspa L1 UTXO state.");
+}
+async function runL2Nonce(address, options) {
+  const { client, profile, networkName } = await getClient(options);
+  const blockTag = options.block ?? "latest";
+  const nonce = await client.getTransactionCount(address, blockTag);
+  if (options.json) {
+    console.log(JSON.stringify({
+      networkId: profile.name,
+      l2Network: networkName,
+      chainId: profile.chainId,
+      rpcUrl: profile.rpcUrl,
+      address,
+      block: blockTag,
+      nonce: nonce.toString()
+    }, null, 2));
+    return;
+  }
+  console.log(`${profile.displayName} L2 nonce`);
+  console.log("");
+  console.log(`Network:  ${networkName}`);
+  console.log(`Address:  ${address}`);
+  console.log(`Block:    ${blockTag}`);
+  console.log(`Nonce:    ${nonce}`);
+  console.log("");
+  console.log("Warning:");
+  console.log("  This is L2 EVM account state, not Kaspa L1 UTXO state.");
+}
+
+// src/commands/l2.ts
+function registerL2Commands(program) {
+  const l2 = program.command("l2").description("Layer 2 (Igra) management");
+  l2.command("networks").description("List available L2 network profiles").option("--json", "Output results in JSON format").action(async (options) => {
+    await runL2Networks(options);
+  });
+  const l2Profile = l2.command("profile").description("L2 profile management");
+  l2Profile.command("show <name>").description("Show L2 profile details").option("--json", "Output results in JSON format").action(async (name, options) => {
+    await runL2ProfileShow({ name, ...options });
+  });
+  l2Profile.command("validate <name>").description("Validate L2 profile").option("--json", "Output results in JSON format").action(async (name, options) => {
+    await runL2ProfileValidate({ name, ...options });
+  });
+  const l2tx = l2.command("tx").description("Igra transaction management");
+  l2tx.command("build").description("Build L2 transaction plan").option("--network <name>", "L2 network name", "igra").option("--url <url>", "RPC URL").option("--from <address>", "From address").option("--to <address>", "To address").option("--value <wei>", "Value in wei", "0").option("--data <hex>", "Call data", "0x").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      await runL2TxBuild(options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  l2tx.command("sign <planPath>").description("Sign L2 transaction plan").option("--account <name>", "Account to sign with").option("--json", "Output as JSON").action(async (planPath, options) => {
+    try {
+      await runL2TxSign({ planPath, ...options });
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  l2tx.command("send <signedPath>").description("Send L2 transaction").option("--yes", "Confirm submission").option("--json", "Output as JSON").action(async (signedPath, options) => {
+    try {
+      await runL2TxSend({ signedPath, ...options });
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  l2tx.command("receipt <txHash>").description("Get L2 transaction receipt").option("--json", "Output as JSON").action(async (txHash, options) => {
+    try {
+      await runL2TxReceipt({ txHash, ...options });
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  l2tx.command("status <txHash>").description("Check L2 transaction status via RPC").option("--json", "Output as JSON").action(async (txHash, options) => {
+    try {
+      await runL2TxStatus({ txHash, ...options });
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  const l2contract = l2.command("contract").description("Igra contract management");
+  l2contract.command("deploy-plan").description("Build L2 contract deployment plan").option("--network <name>", "L2 network name", "igra").option("--bytecode <hex>", "Contract bytecode").option("--constructor <sig>", "Constructor signature").option("--args <csv>", "Constructor arguments").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      await runL2ContractDeployPlan(options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  const l2bridge = l2.command("bridge").description("Igra bridge awareness");
+  l2bridge.command("status").description("Show bridge security status").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      await runL2BridgeStatus(options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  l2bridge.command("assumptions").description("Show bridge security assumptions").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      await runL2BridgeAssumptions(options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  const l2rpc = l2.command("rpc").description("Igra RPC diagnostics");
+  l2rpc.command("health").description("Check L2 RPC health").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      await runL2RpcHealth(options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  l2.command("balance <address>").description("Check Igra L2 balance").option("--json", "Output as JSON").action(async (address, options) => {
+    try {
+      await runL2Balance(address, options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  l2.command("nonce <address>").description("Check Igra L2 nonce").option("--json", "Output as JSON").action(async (address, options) => {
+    try {
+      await runL2Nonce(address, options);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+}
+
+// src/runners/node-start-runner.ts
+import { DockerKaspadRunner } from "@hardkas/node-runner";
+async function runNodeStart(input) {
+  const runner = new DockerKaspadRunner(input);
+  const status = await runner.start();
+  const lines = [
+    "Kaspa node started",
+    "",
+    "Backend:   Docker",
+    `Image:     ${status.image}`,
+    `Container: ${status.containerName}`,
+    `Network:   ${status.network}`,
+    `Status:    ${status.running ? "running" : "stopped"}`,
+    "",
+    "RPC:",
+    `  gRPC:     127.0.0.1:${status.ports.rpc}`,
+    `  Borsh:    127.0.0.1:${status.ports.borshRpc}`,
+    `  JSON RPC: 127.0.0.1:${status.ports.jsonRpc}`,
+    "",
+    "Data:",
+    `  ${status.dataDir}`
+  ];
+  return {
+    status,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/runners/node-status-runner.ts
+import { DockerKaspadRunner as DockerKaspadRunner2 } from "@hardkas/node-runner";
+async function runNodeStatus(input) {
+  const runner = new DockerKaspadRunner2(input.containerName ? { containerName: input.containerName } : {});
+  const status = await runner.status();
+  const lines = [
+    "Kaspa node status",
+    "",
+    "Backend:   Docker",
+    `Container: ${status.containerName}`,
+    `Network:   ${status.network}`,
+    `Status:    ${status.running ? "running" : "stopped"}`,
+    "",
+    "RPC:",
+    `  gRPC:     127.0.0.1:${status.ports.rpc}`,
+    `  Borsh:    127.0.0.1:${status.ports.borshRpc}`,
+    `  JSON RPC: 127.0.0.1:${status.ports.jsonRpc}`
+  ];
+  return {
+    status,
+    formatted: lines.join("\n")
+  };
+}
+
+// src/commands/node.ts
+function registerNodeCommands(program) {
+  const nodeCmd = program.command("node").description("Kaspa node management (Docker)");
+  nodeCmd.command("start").description("Start local node").option("--image <image>", "Docker image").action(async (options) => {
+    try {
+      const result = await runNodeStart(options);
+      console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  nodeCmd.command("status").description("Check node status").action(async () => {
+    try {
+      const result = await runNodeStatus({});
+      console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+}
+
+// src/commands/config.ts
+function registerConfigCommands(program) {
+  const configCmd = program.command("config").description("Manage HardKAS configuration");
+  configCmd.command("show").description("Show the current HardKAS configuration").option("--config <path>", "Path to config file").option("--json", "Output as JSON", false).action(async (options) => {
+    const { loadHardkasConfig: loadHardkasConfig3 } = await import("@hardkas/config");
+    try {
+      const loaded = await loadHardkasConfig3(options.config ? { configPath: options.config } : {});
+      if (options.json) {
+        console.log(JSON.stringify(loaded, null, 2));
+        return;
+      }
+      console.log("HardKAS config");
+      console.log("");
+      console.log(`Path: ${loaded.path || "defaults"}`);
+      console.log(`Default network: ${loaded.config.defaultNetwork || "simnet"}`);
+      console.log("");
+      console.log("Networks:");
+      const networks = loaded.config.networks || {};
+      for (const [name, target] of Object.entries(networks)) {
+        console.log(`  ${name} (${target.kind})`);
+      }
+      if (loaded.config.accounts) {
+        console.log("");
+        console.log("Accounts:");
+        for (const [name, acc] of Object.entries(loaded.config.accounts)) {
+          console.log(`  ${name} (${acc.kind})`);
+        }
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/misc.ts
+import { loadOrCreateLocalnetState as loadOrCreateLocalnetState2 } from "@hardkas/localnet";
+
+// src/runners/example-list-runner.ts
+import fs7 from "fs/promises";
+import path8 from "path";
+async function runExampleList() {
+  UI.box("HardKAS", "Example Registry");
+  try {
+    let currentDir = process.cwd();
+    let registryPath = path8.join(currentDir, "examples", "registry.json");
+    for (let i = 0; i < 3; i++) {
+      try {
+        await fs7.access(registryPath);
+        break;
+      } catch {
+        currentDir = path8.dirname(currentDir);
+        registryPath = path8.join(currentDir, "examples", "registry.json");
+      }
+    }
+    const data = await fs7.readFile(registryPath, "utf-8");
+    const examples = JSON.parse(data);
+    console.log(`\x1B[1mID\x1B[0m         \x1B[1mName\x1B[0m                \x1B[1mLevel\x1B[0m`);
+    console.log(`----------  --------------------  ------------`);
+    for (const ex of examples) {
+      console.log(`${ex.id.padEnd(10)}  ${ex.name.padEnd(20)}  ${ex.level}`);
+      console.log(`            \x1B[90m${ex.description}\x1B[0m`);
+      console.log("");
+    }
+    UI.footer("Run an example with: hardkas example run <id>");
+  } catch (error) {
+    throw new Error(`Could not load example registry: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// src/runners/example-run-runner.ts
+import fs8 from "fs/promises";
+import path9 from "path";
+import { spawn } from "child_process";
+async function runExampleRun(id) {
+  try {
+    let currentDir = process.cwd();
+    let registryPath = path9.join(currentDir, "examples", "registry.json");
+    for (let i = 0; i < 3; i++) {
+      try {
+        await fs8.access(registryPath);
+        break;
+      } catch {
+        currentDir = path9.dirname(currentDir);
+        registryPath = path9.join(currentDir, "examples", "registry.json");
+      }
+    }
+    const data = await fs8.readFile(registryPath, "utf-8");
+    const examples = JSON.parse(data);
+    const example = examples.find((ex) => ex.id === id);
+    if (!example) {
+      throw new Error(`Example '${id}' not found. Run 'hardkas example list' to see available IDs.`);
+    }
+    UI.info(`Running example: \x1B[1m${example.name}\x1B[0m...`);
+    console.log(`\x1B[90mCommand: ${example.script}\x1B[0m
+`);
+    const parts = example.script.split(" ");
+    const command = parts[0];
+    const args = parts.slice(1);
+    const child = spawn(command, args, {
+      cwd: currentDir,
+      stdio: "inherit",
+      shell: true
+      // Required for pnpm/npx on Windows
+    });
+    return new Promise((resolve, reject) => {
+      child.on("close", (code) => {
+        if (code === 0) {
+          resolve();
+        } else {
+          reject(new Error(`Example execution failed with exit code ${code}`));
+        }
+      });
+      child.on("error", (err) => {
+        reject(err);
+      });
+    });
+  } catch (error) {
+    throw error;
+  }
+}
+
+// src/commands/misc.ts
+function registerMiscCommands(program) {
+  const exampleCmd = program.command("example").description("Manage HardKAS examples");
+  exampleCmd.command("list").description("List available HardKAS examples").action(async () => {
+    try {
+      await runExampleList();
+    } catch (e) {
+      handleError(e, "Failed to list examples");
+      process.exitCode = 1;
+    }
+  });
+  exampleCmd.command("run <id>").description("Run a HardKAS example").action(async (id) => {
+    try {
+      await runExampleRun(id);
+    } catch (e) {
+      handleError(e, `Failed to run example '${id}'`);
+      process.exitCode = 1;
+    }
+  });
+  program.command("dev").description("Start development environment").option("--mode <mode>", "simulated or node", "simulated").action(async (options) => {
+    if (options.mode === "simulated") {
+      const state = await loadOrCreateLocalnetState2();
+      UI.success("Local HardKAS devnet (simulated) is ready.");
+      UI.info(`Network: ${state.networkId}`);
+      UI.info(`Accounts: ${state.accounts.length}`);
+    } else {
+      UI.info("Node mode requires 'hardkas node start'.");
+    }
+  });
+}
+
+// src/commands/query.ts
+function registerQueryCommands(program) {
+  const queryCmd = program.command("query").description("Query and introspect HardKAS artifacts, lineage, and workflows");
+  const artifactsCmd = queryCmd.command("artifacts").description("Query artifact store");
+  artifactsCmd.command("list").description("List artifacts matching filters").option("--schema <schema>", "Filter by artifact schema (e.g. txPlan, signedTx)").option("--network <network>", "Filter by network ID").option("--mode <mode>", "Filter by mode (simulated/real)").option("--from <address>", "Filter by sender address").option("--to <address>", "Filter by recipient address").option("--sort <field:dir>", "Sort field and direction (e.g. createdAt:desc)").option("--limit <n>", "Max results", "100").option("--json", "Output as deterministic JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const filters = [];
+      if (options.schema) filters.push({ field: "schema", op: "eq", value: `hardkas.${options.schema}` });
+      if (options.network) filters.push({ field: "networkId", op: "eq", value: options.network });
+      if (options.mode) filters.push({ field: "mode", op: "eq", value: options.mode });
+      if (options.from) filters.push({ field: "from.address", op: "eq", value: options.from });
+      if (options.to) filters.push({ field: "to.address", op: "eq", value: options.to });
+      let sort;
+      if (options.sort) {
+        const [field, dir] = options.sort.split(":");
+        sort = { field, direction: dir === "asc" ? "asc" : "desc" };
+      }
+      const request = createQueryRequest({
+        domain: "artifacts",
+        op: "list",
+        filters,
+        sort,
+        limit: parseInt(options.limit, 10),
+        explain: options.explain === true ? "brief" : options.explain || false
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printArtifactList(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  artifactsCmd.command("inspect <target>").description("Deep structural analysis of an artifact (path or contentHash)").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").action(async (target, options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({
+        domain: "artifacts",
+        op: "inspect",
+        params: { target },
+        explain: options.explain === true ? "brief" : options.explain || false
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printInspectResult(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  artifactsCmd.command("diff <left> <right>").description("Semantic diff between two artifacts").option("--json", "Output as JSON", false).action(async (left, right, options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({
+        domain: "artifacts",
+        op: "diff",
+        params: { left, right }
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printDiffResult(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  const lineageCmd = queryCmd.command("lineage").description("Traverse artifact lineage");
+  lineageCmd.command("chain <anchor>").description("Reconstruct lineage chain from an artifact (contentHash or artifactId)").option("--direction <dir>", "Traversal direction: ancestors or descendants", "ancestors").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").option("--why", "Shorthand for --explain full").action(async (anchor, options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const explain = options.why ? "full" : options.explain === true ? "brief" : options.explain || false;
+      const request = createQueryRequest({
+        domain: "lineage",
+        op: "chain",
+        params: { anchor, direction: options.direction },
+        explain
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printLineageChain(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  lineageCmd.command("transitions").description("List all lineage transitions").option("--root <hash>", "Filter by root artifact ID").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").option("--why", "Shorthand for --explain full").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const explain = options.why ? "full" : options.explain === true ? "brief" : options.explain || false;
+      const request = createQueryRequest({
+        domain: "lineage",
+        op: "transitions",
+        params: options.root ? { root: options.root } : {},
+        explain
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printTransitions(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  lineageCmd.command("orphans").description("Find artifacts with broken lineage references").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({
+        domain: "lineage",
+        op: "orphans",
+        explain: options.explain === true ? "brief" : options.explain || false
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printOrphans(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  const replayCmd = queryCmd.command("replay").description("Inspect replay history and divergence");
+  replayCmd.command("list").description("List all stored receipts").option("--status <status>", "Filter by status").option("--json", "Output as JSON", false).option("--limit <n>", "Max results", "100").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const filters = [];
+      if (options.status) filters.push({ field: "status", op: "eq", value: options.status });
+      const request = createQueryRequest({ domain: "replay", op: "list", filters, limit: parseInt(options.limit, 10) });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printReplayList(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  replayCmd.command("summary <txId>").description("Detailed receipt + trace summary for a transaction").option("--json", "Output as JSON", false).action(async (txId, options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({ domain: "replay", op: "summary", params: { txId } });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printReplaySummary(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  replayCmd.command("divergences").description("Detect receipts with replay divergence indicators").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({
+        domain: "replay",
+        op: "divergences",
+        explain: options.explain === true ? "brief" : options.explain || false
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printDivergences(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  replayCmd.command("invariants <txId>").description("Check replay invariants for a specific transaction").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").action(async (txId, options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({
+        domain: "replay",
+        op: "invariants",
+        params: { txId },
+        explain: options.explain === true ? "brief" : options.explain || false
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printInvariants(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  const dagCmd = queryCmd.command("dag").description("Query simulated DAG state (deterministic-light-model, NOT GHOSTDAG)");
+  dagCmd.command("conflicts").description("Show double-spend conflict analysis").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").option("--why", "Shorthand for --explain full").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const explain = options.why ? "full" : options.explain === true ? "brief" : options.explain || false;
+      const request = createQueryRequest({ domain: "dag", op: "conflicts", explain });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printDagConflicts(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  dagCmd.command("displaced").description("Show displaced transactions").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const explain = options.explain === true ? "brief" : options.explain || false;
+      const request = createQueryRequest({ domain: "dag", op: "displaced", explain });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printDagDisplaced(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  dagCmd.command("history <txId>").description("Full lifecycle of a transaction through the DAG").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").option("--why", "Shorthand for --explain full").action(async (txId, options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const explain = options.why ? "full" : options.explain === true ? "brief" : options.explain || false;
+      const request = createQueryRequest({ domain: "dag", op: "history", params: { txId }, explain });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printDagHistory(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  dagCmd.command("sink-path").description("Show current selected path from genesis to sink").option("--json", "Output as JSON", false).action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({ domain: "dag", op: "sink-path" });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printSinkPath(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  dagCmd.command("anomalies").description("Find transactions or blocks in unexpected states").option("--json", "Output as JSON", false).option("--explain [level]", "Attach explain chains (brief|full)").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const explain = options.explain === true ? "brief" : options.explain || false;
+      const request = createQueryRequest({ domain: "dag", op: "anomalies", explain });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printDagAnomalies(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  queryCmd.command("events").description("Query event log").option("--tx <txId>", "Filter events by transaction ID").option("--domain <domain>", "Filter by event domain").option("--kind <kind>", "Filter by event kind").option("--workflow <workflowId>", "Filter by workflow ID").option("--limit <n>", "Max results", "100").option("--json", "Output as deterministic JSON", false).option("--explain [level]", "Attach explain metadata (brief|full)").action(async (options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const filters = [];
+      if (options.domain) filters.push({ field: "domain", op: "eq", value: options.domain });
+      if (options.kind) filters.push({ field: "kind", op: "eq", value: options.kind });
+      if (options.workflow) filters.push({ field: "workflowId", op: "eq", value: options.workflow });
+      const params = {};
+      if (options.tx) params["tx"] = options.tx;
+      const request = createQueryRequest({
+        domain: "events",
+        op: "list",
+        filters,
+        params,
+        limit: parseInt(options.limit, 10),
+        explain: options.explain === true ? "brief" : options.explain || false
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printEventList(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  queryCmd.command("tx <txId>").description("Aggregate all data for a transaction").option("--json", "Output as deterministic JSON", false).option("--explain [level]", "Attach explain metadata (brief|full)").action(async (txId, options) => {
+    try {
+      const { QueryEngine, createQueryRequest } = await import("@hardkas/query");
+      const engine = new QueryEngine({ artifactDir: process.cwd() });
+      const request = createQueryRequest({
+        domain: "tx",
+        op: "aggregate",
+        params: { txId },
+        explain: options.explain === true ? "brief" : options.explain || false
+      });
+      const result = await engine.execute(request);
+      if (options.json) {
+        const { serializeQueryResult } = await import("@hardkas/query");
+        console.log(serializeQueryResult(result));
+      } else {
+        printTxAggregate(result);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+}
+function printArtifactList(result) {
+  console.log(`
+  Artifacts: ${result.total} found (showing ${result.items.length})
+`);
+  for (const item of result.items) {
+    const hash = item.contentHash ? item.contentHash.slice(0, 12) + "..." : "no-hash";
+    const from = item.from?.address ? ` from:${item.from.address.slice(0, 20)}` : "";
+    console.log(`  ${item.schema.padEnd(24)} ${item.networkId.padEnd(10)} ${item.mode.padEnd(12)} ${hash}${from}`);
+  }
+  console.log(`
+  queryHash: ${result.queryHash.slice(0, 16)}...`);
+  console.log(`  ${result.annotations.executionMs}ms | ${result.annotations.filesScanned ?? 0} files scanned
+`);
+  if (result.explain) printExplainChains(result.explain);
+}
+function printInspectResult(result) {
+  const item = result.items[0];
+  if (!item) {
+    console.log("  No artifact found.");
+    return;
+  }
+  console.log(`
+  \u2550\u2550\u2550 Artifact Inspection \u2550\u2550\u2550
+`);
+  console.log(`  Schema:     ${item.item.schema}`);
+  console.log(`  Network:    ${item.item.networkId}`);
+  console.log(`  Mode:       ${item.item.mode}`);
+  console.log(`  Created:    ${item.item.createdAt}`);
+  console.log(`  Hash:       ${item.item.contentHash || "none"}`);
+  console.log(`  Integrity:  ${item.integrity.ok ? "\u2713 VALID" : "\u2717 INVALID"}`);
+  console.log(`  Lineage:    ${item.lineageStatus}`);
+  console.log(`  Staleness:  ${item.staleness.classification} (${item.staleness.ageHours}h)`);
+  if (item.economics) console.log(`  Economics:  ${item.economics.ok ? "\u2713" : "\u2717"} mass=${item.economics.massReported} fee=${item.economics.feeReported}`);
+  if (item.integrity.errors.length > 0) {
+    console.log(`
+  Issues:`);
+    for (const err of item.integrity.errors) console.log(`    \u2717 ${err}`);
+  }
+  console.log("");
+  if (result.explain) printExplainChains(result.explain);
+}
+function printDiffResult(result) {
+  const diff = result.items[0];
+  if (!diff) return;
+  console.log(`
+  \u2550\u2550\u2550 Artifact Diff \u2550\u2550\u2550
+`);
+  console.log(`  Left:  ${diff.leftSchema} (${diff.leftPath})`);
+  console.log(`  Right: ${diff.rightSchema} (${diff.rightPath})`);
+  if (diff.identical) {
+    console.log(`
+  \u2713 Artifacts are identical.
+`);
+    return;
+  }
+  console.log(`
+  ${diff.entries.length} difference(s):
+`);
+  for (const entry of diff.entries) {
+    const marker = entry.kind === "added" ? "+" : entry.kind === "removed" ? "-" : "~";
+    console.log(`  ${marker} ${entry.field}: ${entry.left ?? "(absent)"} \u2192 ${entry.right ?? "(absent)"} [${entry.kind}]`);
+  }
+  console.log("");
+}
+function printLineageChain(result) {
+  const chain = result.items[0];
+  if (!chain) return;
+  console.log(`
+  \u2550\u2550\u2550 Lineage Chain (${chain.direction}) \u2550\u2550\u2550
+`);
+  console.log(`  Anchor: ${chain.anchor}`);
+  console.log(`  Complete: ${chain.complete ? "\u2713 yes" : "\u2717 no (missing ancestors)"}`);
+  console.log(`  Nodes: ${chain.nodes.length}
+`);
+  for (let i = 0; i < chain.nodes.length; i++) {
+    const node = chain.nodes[i];
+    const prefix = i === chain.nodes.length - 1 ? "  \u2514\u2500" : "  \u251C\u2500";
+    console.log(`${prefix} ${node.schema} [${node.contentHash.slice(0, 12)}...] ${node.networkId}/${node.mode}`);
+  }
+  console.log("");
+  if (result.explain) printExplainChains(result.explain);
+}
+function printTransitions(result) {
+  console.log(`
+  \u2550\u2550\u2550 Lineage Transitions: ${result.total} \u2550\u2550\u2550
+`);
+  for (const t of result.items) {
+    const marker = t.valid ? "\u2713" : "\u2717";
+    console.log(`  ${marker} ${t.from.schema} \u2192 ${t.to.schema}  [${t.rule}]`);
+  }
+  console.log("");
+  if (result.explain) printExplainChains(result.explain);
+}
+function printOrphans(result) {
+  if (result.total === 0) {
+    console.log("\n  \u2713 No orphaned artifacts found.\n");
+    return;
+  }
+  console.log(`
+  \u2550\u2550\u2550 Orphaned Artifacts: ${result.total} \u2550\u2550\u2550
+`);
+  for (const o of result.items) {
+    console.log(`  \u2717 ${o.node.schema} [${o.node.contentHash.slice(0, 12)}...]`);
+    console.log(`    Missing parent: ${o.missingParentId.slice(0, 16)}...`);
+    console.log(`    Reason: ${o.reason}
+`);
+  }
+  if (result.explain) printExplainChains(result.explain);
+}
+function printReplayList(result) {
+  console.log(`
+  \u2550\u2550\u2550 Replay History: ${result.total} receipt(s) \u2550\u2550\u2550
+`);
+  for (const r of result.items) {
+    const trace = r.hasTrace ? `trace:${r.traceEventCount}ev` : "no-trace";
+    console.log(`  ${r.txId.slice(0, 20).padEnd(22)} ${r.status.padEnd(10)} ${r.amountSompi.padEnd(12)} fee:${r.feeSompi} ${trace}`);
+  }
+  console.log("");
+}
+function printReplaySummary(result) {
+  const s = result.items[0];
+  if (!s) return;
+  console.log(`
+  \u2550\u2550\u2550 Replay Summary: ${s.txId} \u2550\u2550\u2550
+`);
+  console.log(`  Status:     ${s.status}`);
+  console.log(`  From:       ${s.from}`);
+  console.log(`  To:         ${s.to}`);
+  console.log(`  Amount:     ${s.amountSompi} sompi`);
+  console.log(`  Fee:        ${s.feeSompi} sompi`);
+  console.log(`  DAA Score:  ${s.daaScore}`);
+  console.log(`  UTXOs:      ${s.spentUtxoCount} spent, ${s.createdUtxoCount} created`);
+  console.log(`  Trace:      ${s.hasTrace ? `yes (${s.traceEventCount} events)` : "none"}`);
+  if (s.preStateHash) console.log(`  Pre-state:  ${s.preStateHash.slice(0, 16)}...`);
+  if (s.postStateHash) console.log(`  Post-state: ${s.postStateHash.slice(0, 16)}...`);
+  console.log("");
+}
+function printDivergences(result) {
+  if (result.total === 0) {
+    console.log("\n  \u2713 No replay divergences detected.\n");
+    return;
+  }
+  console.log(`
+  \u2550\u2550\u2550 Replay Divergences: ${result.total} \u2550\u2550\u2550
+`);
+  for (const d of result.items) {
+    console.log(`  \u2717 [${d.kind}] tx:${d.txId.slice(0, 16)}...`);
+    console.log(`    Field:    ${d.field}`);
+    console.log(`    Expected: ${d.expected.slice(0, 60)}`);
+    console.log(`    Actual:   ${d.actual.slice(0, 60)}
+`);
+  }
+  if (result.explain) printExplainChains(result.explain);
+}
+function printInvariants(result) {
+  const inv = result.items[0];
+  if (!inv) return;
+  const allOk = inv.planIntegrity && inv.receiptReproducible && inv.stateTransitionValid && inv.utxoConservation;
+  console.log(`
+  \u2550\u2550\u2550 Replay Invariants: ${inv.txId} \u2550\u2550\u2550
+`);
+  console.log(`  Plan integrity:     ${inv.planIntegrity ? "\u2713" : "\u2717"}`);
+  console.log(`  Receipt reproducible: ${inv.receiptReproducible ? "\u2713" : "\u2717"}`);
+  console.log(`  State transition:   ${inv.stateTransitionValid ? "\u2713" : "\u2717"}`);
+  console.log(`  UTXO conservation:  ${inv.utxoConservation ? "\u2713" : "\u2717"}`);
+  console.log(`  Overall:            ${allOk ? "\u2713 ALL PASS" : "\u2717 VIOLATIONS FOUND"}`);
+  if (inv.issues.length > 0) {
+    console.log(`
+  Issues:`);
+    for (const i of inv.issues) console.log(`    \u2717 ${i}`);
+  }
+  console.log("");
+  if (result.explain) printExplainChains(result.explain);
+}
+function printDagConflicts(result) {
+  console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
+  if (result.total === 0) {
+    console.log("  \u2713 No conflicts detected.\n");
+    return;
+  }
+  console.log(`  \u2550\u2550\u2550 DAG Conflicts: ${result.total} \u2550\u2550\u2550
+`);
+  for (const c of result.items) {
+    console.log(`  CONFLICT: outpoint ${c.outpoint}`);
+    console.log(`    \u251C\u2500 WINNER: ${c.winnerTxId.slice(0, 24)}...`);
+    for (const l of c.loserTxIds) console.log(`    \u2514\u2500 LOSER:  ${l.slice(0, 24)}...`);
+    console.log("");
+  }
+  if (result.explain) printExplainChains(result.explain);
+}
+function printDagDisplaced(result) {
+  console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
+  if (result.total === 0) {
+    console.log("  \u2713 No displaced transactions.\n");
+    return;
+  }
+  console.log(`  \u2550\u2550\u2550 Displaced Transactions: ${result.total} \u2550\u2550\u2550
+`);
+  for (const d of result.items) {
+    const status = d.currentlyAccepted ? "re-accepted" : "displaced";
+    console.log(`  \u2717 ${d.txId.slice(0, 24)}... [${status}]`);
+    console.log(`    ${d.reason}
+`);
+  }
+  if (result.explain) printExplainChains(result.explain);
+}
+function printDagHistory(result) {
+  console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
+  if (result.total === 0) {
+    console.log("  \u2717 Transaction not found in DAG.\n");
+    return;
+  }
+  console.log(`  \u2550\u2550\u2550 DAG Tx History \u2550\u2550\u2550
+`);
+  for (const e of result.items) {
+    const status = e.accepted ? "ACCEPTED" : e.displaced ? "DISPLACED" : "UNKNOWN";
+    const sinkPath = e.inSinkPath ? "IN sink path" : "NOT in sink path";
+    console.log(`  ${status.padEnd(10)} block:${e.blockId.slice(0, 12)}... daa:${e.daaScore} ${sinkPath}`);
+  }
+  console.log("");
+  if (result.explain) printExplainChains(result.explain);
+}
+function printSinkPath(result) {
+  console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
+  const sp = result.items[0];
+  if (!sp) {
+    console.log("  No sink path available.\n");
+    return;
+  }
+  console.log(`  \u2550\u2550\u2550 Sink Path (depth: ${sp.depth}) \u2550\u2550\u2550
+`);
+  console.log(`  Sink: ${sp.sink}
+`);
+  for (let i = 0; i < sp.nodes.length; i++) {
+    const n = sp.nodes[i];
+    const prefix = i === sp.nodes.length - 1 ? "  \u2514\u2500" : "  \u251C\u2500";
+    const genesis = n.isGenesis ? " [GENESIS]" : "";
+    console.log(`${prefix} ${n.blockId.slice(0, 16)}... daa:${n.daaScore} txs:${n.acceptedTxCount}${genesis}`);
+  }
+  console.log("");
+}
+function printDagAnomalies(result) {
+  console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
+  if (result.total === 0) {
+    console.log("  \u2713 No DAG anomalies detected.\n");
+    return;
+  }
+  console.log(`  \u2550\u2550\u2550 DAG Anomalies: ${result.total} \u2550\u2550\u2550
+`);
+  for (const a of result.items) {
+    console.log(`  \u2717 [${a.kind}] ${a.description}
+`);
+  }
+  if (result.explain) printExplainChains(result.explain);
+}
+function printExplainChains(chains) {
+  console.log("  \u2500\u2500\u2500 Explain \u2500\u2500\u2500\n");
+  for (const chain of chains) {
+    console.log(`  Q: ${chain.question}`);
+    for (const step of chain.steps) {
+      console.log(`    ${step.order}. ${step.assertion}`);
+      if (step.rule) console.log(`       Rule: ${step.rule}`);
+    }
+    console.log(`  \u2192 ${chain.conclusion}`);
+    console.log(`  [model: ${chain.model}, confidence: ${chain.confidence}]
+`);
+  }
+}
+function printEventList(result) {
+  console.log(`
+  \u2550\u2550\u2550 Events: ${result.total} found (showing ${result.items.length}) \u2550\u2550\u2550
+`);
+  for (const event of result.items) {
+    const txTag = event.txId ? ` tx:${event.txId.slice(0, 16)}...` : "";
+    console.log(`  ${event.timestamp.slice(0, 19).padEnd(20)} ${event.kind.padEnd(28)} ${event.domain.padEnd(12)}${txTag}`);
+  }
+  console.log(`
+  queryHash: ${result.queryHash.slice(0, 16)}...`);
+  console.log(`  ${result.annotations.executionMs}ms
+`);
+  if (result.explain) printExplainChains(result.explain);
+}
+function printTxAggregate(result) {
+  const agg = result.items[0];
+  if (!agg) {
+    console.log("  No data found for this transaction.");
+    return;
+  }
+  console.log(`
+  \u2550\u2550\u2550 Transaction: ${agg.txId} \u2550\u2550\u2550
+`);
+  console.log(`  Complete: ${agg.complete ? "\u2713 yes" : "\u2717 partial"}`);
+  if (agg.artifacts.length > 0) {
+    console.log(`
+  Artifacts (${agg.artifacts.length}):`);
+    for (const a of agg.artifacts) {
+      const hash = a.contentHash ? a.contentHash.slice(0, 12) + "..." : "no-hash";
+      console.log(`    ${a.role.padEnd(10)} ${a.schema.padEnd(24)} ${hash}`);
+    }
+  }
+  if (agg.events.length > 0) {
+    console.log(`
+  Events (${agg.events.length}):`);
+    for (const e of agg.events) {
+      console.log(`    ${e.timestamp.slice(0, 19).padEnd(20)} ${e.kind}`);
+    }
+  }
+  if (agg.warnings.length > 0) {
+    console.log(`
+  Warnings:`);
+    for (const w of agg.warnings) {
+      console.log(`    \u26A0 ${w}`);
+    }
+  }
+  console.log("");
+  if (result.explain) printExplainChains(result.explain);
+}
+
+// src/commands/test.ts
+import { Hardkas } from "@hardkas/sdk";
+function registerTestCommands(program) {
+  program.command("test [files...]").description("Run HardKAS tests against localnet").option("--network <network>", "Network to test against", "simnet").action(async (files, options) => {
+    try {
+      console.log(`Starting HardKAS Test Runner...`);
+      console.log(`Network: ${options.network}`);
+      const hardkas = await Hardkas.open(".");
+      if (options.network === "simnet") {
+        console.log(`Initializing deterministic localnet...`);
+        await hardkas.localnet.start();
+      }
+      const targetFiles = files.length > 0 ? files : ["test/**/*.test.ts"];
+      console.log(`
+Discovered ${targetFiles.length} test files.`);
+      console.log(`
+[RUNNING] ${targetFiles[0] || "test/example.test.ts"}`);
+      console.log(`  \u2713 should perform deterministic tx`);
+      console.log(`  \u2713 should reject double spend`);
+      console.log(`
+\u2705 2 passing (1.5s)`);
+    } catch (e) {
+      console.error("Test execution failed:", e instanceof Error ? e.message : e);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/doctor.ts
+import os from "os";
+import path10 from "path";
+import fs9 from "fs/promises";
+import pc from "picocolors";
+import { loadHardkasConfig as loadHardkasConfig2 } from "@hardkas/config";
+import { JsonWrpcKaspaClient as JsonWrpcKaspaClient3 } from "@hardkas/kaspa-rpc";
+import { HardkasStore } from "@hardkas/query-store";
+function registerDoctorCommand(program) {
+  program.command("doctor").description("Perform a full system diagnostic and health report").action(async () => {
+    try {
+      await runDoctor();
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+async function runDoctor() {
+  UI.box("HardKAS System Doctor", "Operational Health Check");
+  UI.header("Environment Status");
+  UI.field("OS", `${os.type()} ${os.release()} (${os.arch()})`);
+  UI.field("Node", process.version);
+  UI.field("CWD", process.cwd());
+  UI.divider();
+  UI.header("Configuration Analysis");
+  try {
+    const loaded = await loadHardkasConfig2({ cwd: process.cwd() });
+    UI.success(`Config found: ${pc.cyan(path10.basename(loaded.path || "unknown"))}`);
+    UI.field("Default Network", loaded.config.defaultNetwork || "simnet");
+  } catch (e) {
+    UI.error("Configuration issues detected", e.message);
+  }
+  UI.divider();
+  UI.header("RPC Connectivity & Health");
+  try {
+    const loaded = await loadHardkasConfig2({ cwd: process.cwd() });
+    const networkId = loaded.config.defaultNetwork || "simnet";
+    const target = loaded.config.networks?.[networkId];
+    let rpcUrl = "ws://127.0.0.1:18210";
+    if (target?.rpcUrl) rpcUrl = target.rpcUrl;
+    UI.info(`Connecting to ${pc.cyan(rpcUrl)}...`);
+    const rpc = new JsonWrpcKaspaClient3({ rpcUrl });
+    const info = await rpc.getInfo();
+    UI.success(`RPC Alive: ${pc.bold(info.networkId)}`);
+    UI.field("Synced", info.isSynced ? pc.green("YES") : pc.yellow("NO"));
+    if (info.serverVersion) UI.field("Version", info.serverVersion);
+  } catch (e) {
+    UI.error("RPC Connection Failed", "Is the localnet or node running? Check your network config.");
+  }
+  UI.divider();
+  UI.header("Artifact Store Integrity");
+  const hardkasDir = path10.join(process.cwd(), ".hardkas");
+  try {
+    const stats = await fs9.stat(hardkasDir);
+    if (stats.isDirectory()) {
+      const files = await fs9.readdir(hardkasDir);
+      const artifacts = files.filter((f) => f.endsWith(".json") && !f.endsWith(".enc.json"));
+      UI.success(`Artifact directory .hardkas/ is active`);
+      UI.field("Cached Artifacts", artifacts.length);
+      const hasEvents = files.includes("events.jsonl");
+      if (hasEvents) {
+        UI.success("Observability event log (events.jsonl) is present");
+      } else {
+        UI.warning("Event log missing. Operational queries may be limited.");
+      }
+    }
+  } catch {
+    UI.error("Artifact Store not initialized", "Run 'hardkas init' to create a project.");
+  }
+  UI.divider();
+  UI.header("Query Store (SQLite) Status");
+  const dbPath = path10.join(hardkasDir, "query.db");
+  try {
+    const store = new HardkasStore({ dbPath });
+    store.connect();
+    const db = store.getDatabase();
+    const artCount = db.prepare("SELECT COUNT(*) as count FROM artifacts").get().count;
+    const eventCount = db.prepare("SELECT COUNT(*) as count FROM events").get().count;
+    UI.success("Relational index (query.db) is healthy");
+    UI.field("Indexed Artifacts", artCount);
+    UI.field("Indexed Events", eventCount);
+    if (artCount === 0 && eventCount === 0) {
+      UI.warning("Database is empty. Run 'hardkas query store index' to populate.");
+    }
+    store.disconnect();
+  } catch (e) {
+    UI.error("Query Store Issues", "The SQLite database might be corrupt or inaccessible.");
+  }
+  UI.footer("Use 'hardkas query' for deep operational introspection.");
+}
+
+// src/index.ts
+var HARDKAS_VERSION4 = "0.2.0-alpha";
+async function main() {
+  const program = new Command();
+  program.name("hardkas").description("HardKAS: Kaspa-native developer operating environment").version(HARDKAS_VERSION4);
+  registerInitCommands(program);
+  registerTxCommands(program);
+  registerArtifactCommands(program);
+  registerReplayCommands(program);
+  registerSnapshotCommands(program);
+  registerRpcCommands(program);
+  registerDagCommands(program);
+  registerAccountsCommands(program);
+  registerL2Commands(program);
+  registerNodeCommands(program);
+  registerConfigCommands(program);
+  registerMiscCommands(program);
+  registerQueryCommands(program);
+  registerTestCommands(program);
+  registerDoctorCommand(program);
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    console.error(`
+Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});