@hardkas/cli 0.2.1-alpha → 0.2.2-alpha.1

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   UI,
   handleError
-} from "./chunk-M54KNJEH.js";
+} from "./chunk-AQWQW5ZG.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -70,19 +70,19 @@ async function runUp() {
 
 // 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) => {
+  program.command("init").description(`Initialize a new HardKAS project ${UI.maturity("stable")}`).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");
+      const path12 = await import("path");
       let targetDir = process.cwd();
       if (name) {
-        targetDir = path11.join(process.cwd(), name);
+        targetDir = path12.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");
+      const configFile = path12.join(targetDir, "hardkas.config.ts");
+      const pkgFile = path12.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;
@@ -102,7 +102,7 @@ function registerInitCommands(program) {
       const template = `import { defineHardkasConfig } from "@hardkas/sdk";
 
 export default defineHardkasConfig({
-  // HardKAS v0.2-alpha Configuration
+  // HardKAS v0.2.2-alpha Configuration
   defaultNetwork: "simnet",
 
   networks: {
@@ -120,16 +120,28 @@ export default defineHardkasConfig({
   accounts: {
     alice: {
       kind: "simulated",
-      address: "kaspasim:sim_alice"
+      address: "kaspa:sim_alice"
     },
     bob: {
       kind: "simulated",
-      address: "kaspasim:sim_bob"
+      address: "kaspa:sim_bob"
     }
   }
 });
 `;
       fs10.writeFileSync(configFile, template, "utf-8");
+      const gitIgnoreFile = path12.join(targetDir, ".gitignore");
+      const gitIgnoreEntry = "\n# HardKAS local storage\n.hardkas/\n";
+      if (!fs10.existsSync(gitIgnoreFile)) {
+        fs10.writeFileSync(gitIgnoreFile, gitIgnoreEntry, "utf-8");
+        UI.info("Created: .gitignore");
+      } else {
+        const content = fs10.readFileSync(gitIgnoreFile, "utf-8");
+        if (!content.includes(".hardkas/")) {
+          fs10.appendFileSync(gitIgnoreFile, gitIgnoreEntry, "utf-8");
+          UI.info("Updated: .gitignore (added .hardkas/)");
+        }
+      }
       UI.success(`HardKAS project '${name || "current"}' initialized successfully.`);
       if (name) UI.info(`Project folder: ${targetDir}`);
       UI.info(`Created: hardkas.config.ts (v0.2-alpha)`);
@@ -139,7 +151,7 @@ export default defineHardkasConfig({
       process.exitCode = 1;
     }
   });
-  program.command("up").description("Boot or validate the HardKAS developer runtime environment").action(async () => {
+  program.command("up").description(`Boot or validate the HardKAS developer runtime environment ${UI.maturity("stable")}`).action(async () => {
     try {
       await runUp();
     } catch (e) {
@@ -234,8 +246,8 @@ async function runTxPlan(input) {
     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 { loadOrCreateLocalnetState: loadOrCreateLocalnetState4, getSpendableUtxos } = await import("@hardkas/localnet");
+      const localState = await loadOrCreateLocalnetState4();
       const unspent = getSpendableUtxos(localState, fromAddress);
       availableUtxos = unspent.map((u) => ({
         outpoint: {
@@ -248,17 +260,17 @@ async function runTxPlan(input) {
       }));
       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");
+      const { JsonWrpcKaspaClient: JsonWrpcKaspaClient5 } = await import("@hardkas/kaspa-rpc");
+      const { resolveRuntimeConfig: resolveRuntimeConfig2 } = await import("@hardkas/node-orchestrator");
       rpcUrl = url || target.rpcUrl;
       if (!rpcUrl && target.kind === "kaspa-node") {
-        rpcUrl = resolveRuntimeConfig({
+        rpcUrl = resolveRuntimeConfig2({
           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 client = new JsonWrpcKaspaClient5({ rpcUrl });
       const rpcUtxos = await client.getUtxosByAddress(fromAddress);
       await client.close();
       availableUtxos = rpcUtxos.map((u) => ({
@@ -271,13 +283,13 @@ async function runTxPlan(input) {
     }
   } catch (e) {
     if (url || networkId !== "simnet") {
-      const { JsonWrpcKaspaClient: JsonWrpcKaspaClient4 } = await import("@hardkas/kaspa-rpc");
-      const { resolveRuntimeConfig } = await import("@hardkas/node-orchestrator");
+      const { JsonWrpcKaspaClient: JsonWrpcKaspaClient5 } = await import("@hardkas/kaspa-rpc");
+      const { resolveRuntimeConfig: resolveRuntimeConfig2 } = await import("@hardkas/node-orchestrator");
       rpcUrl = url;
       if (!rpcUrl) {
-        rpcUrl = resolveRuntimeConfig({ network: networkId }).rpcUrl;
+        rpcUrl = resolveRuntimeConfig2({ network: networkId }).rpcUrl;
       }
-      const client = new JsonWrpcKaspaClient4({ rpcUrl });
+      const client = new JsonWrpcKaspaClient5({ rpcUrl });
       const rpcUtxos = await client.getUtxosByAddress(fromAddress);
       await client.close();
       availableUtxos = rpcUtxos.map((u) => ({
@@ -413,6 +425,7 @@ async function runTxSend(input) {
       schema: ARTIFACT_SCHEMAS.TX_RECEIPT,
       hardkasVersion: HARDKAS_VERSION,
       version: ARTIFACT_VERSION,
+      hashVersion: "sha256-canonical",
       networkId: resolvedName,
       mode: "simulated",
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -432,6 +445,7 @@ async function runTxSend(input) {
       schema: ARTIFACT_SCHEMAS.TX_TRACE,
       hardkasVersion: HARDKAS_VERSION,
       version: ARTIFACT_VERSION,
+      hashVersion: "sha256-canonical",
       createdAt: receipt.createdAt,
       txId: receipt.txId,
       mode: "simulated",
@@ -471,6 +485,7 @@ Receipt: ${receiptPath}`
       schema: ARTIFACT_SCHEMAS.TX_RECEIPT,
       hardkasVersion: HARDKAS_VERSION,
       version: ARTIFACT_VERSION,
+      hashVersion: "sha256-canonical",
       networkId: resolvedName,
       mode: "real",
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -666,19 +681,19 @@ async function runTxReceipt(input) {
 // 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) => {
+  tx.command("profile <path>").description("Show detailed mass and fee breakdown for a transaction plan").action(async (path12) => {
     try {
-      await runTxProfile({ path: path11 });
+      await runTxProfile({ path: path12 });
     } 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) => {
+  tx.command("plan").description(`Build a transaction plan artifact ${UI.maturity("stable")}`).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 { loadHardkasConfig: loadHardkasConfig5 } = await import("@hardkas/config");
       const { writeArtifact: writeArtifact4, formatTxPlanArtifact } = await import("@hardkas/artifacts");
-      const loaded = await loadHardkasConfig3();
+      const loaded = await loadHardkasConfig5();
       const artifact = await runTxPlan({
         from: options.from || "alice",
         to: options.to || "bob",
@@ -700,12 +715,12 @@ Artifact saved to: ${options.out}`);
       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) => {
+  tx.command("sign <planPath>").description(`Sign a transaction plan artifact ${UI.maturity("stable")}`).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 { loadHardkasConfig: loadHardkasConfig5 } = await import("@hardkas/config");
       const planArtifact = await readTxPlanArtifact(planPath);
-      const loaded = await loadHardkasConfig3();
+      const loaded = await loadHardkasConfig5();
       const signedArtifact = await runTxSign({
         planArtifact,
         ...options.account ? { accountName: options.account } : {},
@@ -724,10 +739,10 @@ Signed artifact saved to: ${options.out}`);
       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) => {
+  tx.command("send [signedPath]").description(`Broadcast a signed transaction or send directly ${UI.maturity("stable")}`).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();
+      const { loadHardkasConfig: loadHardkasConfig5 } = await import("@hardkas/config");
+      const loaded = await loadHardkasConfig5();
       if (signedPath) {
         const { readSignedTxArtifact } = await import("@hardkas/artifacts");
         const signedArtifact = await readSignedTxArtifact(signedPath);
@@ -777,12 +792,12 @@ Signed artifact saved to: ${options.out}`);
       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("verify <path>").description(`Perform deep semantic verification of a transaction plan ${UI.maturity("preview")}`).option("--json", "Output as JSON", false).action(async (path12, options) => {
+    const { runTxVerify } = await import("./tx-verify-runner-Z5M2JDRI.js");
+    await runTxVerify({ path: path12, ...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");
+  tx.command("trace <txId>").description(`Reconstruct the full operational trace of a transaction ${UI.maturity("research")}`).action(async (txId) => {
+    const { UI: UI2 } = await import("./ui-OVK5PX6H.js");
     UI2.error("Tracing is temporarily disabled while the query API stabilizes.");
     process.exitCode = 1;
   });
@@ -984,26 +999,26 @@ async function runArtifactExplain(options) {
 // 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) => {
+  artifactCmd.command("verify <path>").description(`Verify an artifact's integrity and schema ${UI.maturity("stable")}`).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 (path12, options) => {
     try {
-      await runArtifactVerify({ path: path11, ...options });
+      await runArtifactVerify({ path: path12, ...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) => {
+  artifactCmd.command("explain <path>").description(`Provide a human-readable operational summary of an artifact ${UI.maturity("preview")}`).action(async (path12) => {
     try {
-      await runArtifactExplain({ path: path11 });
+      await runArtifactExplain({ path: path12 });
     } catch (e) {
       handleError(e);
       process.exitCode = 1;
     }
   });
-  artifactCmd.command("lineage <path>").description("Show the provenance and operational history of an artifact").action(async (path11) => {
+  artifactCmd.command("lineage <path>").description(`Show the provenance and operational history of an artifact ${UI.maturity("preview")}`).action(async (path12) => {
     try {
-      const { runArtifactLineage } = await import("./artifact-lineage-runner-EPT6ABS2.js");
-      await runArtifactLineage({ path: path11 });
+      const { runArtifactLineage } = await import("./artifact-lineage-runner-RJWQ3R3X.js");
+      await runArtifactLineage({ path: path12 });
     } catch (e) {
       handleError(e);
       process.exitCode = 1;
@@ -1014,9 +1029,9 @@ function registerArtifactCommands(program) {
 // 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 });
+  replayCmd.command("verify <path>").description("Verify replay invariants for a directory of artifacts").action(async (path12) => {
+    const { runReplayVerify } = await import("./replay-verify-runner-UMYALHNT.js");
+    await runReplayVerify({ path: path12 });
   });
 }
 
@@ -1024,11 +1039,11 @@ function registerReplayCommands(program) {
 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");
+    const { runSnapshotVerify } = await import("./snapshot-verify-runner-BWRW3NUW.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");
+    const { runSnapshotRestore } = await import("./snapshot-restore-runner-QNAADGBX.js");
     await runSnapshotRestore({ idOrName });
   });
 }
@@ -1215,7 +1230,7 @@ function registerRpcCommands(program) {
     }
   });
   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");
+    const { runRpcDoctor } = await import("./rpc-doctor-runner-ERWXOXSE.js");
     try {
       await runRpcDoctor(options);
     } catch (e) {
@@ -1250,7 +1265,7 @@ 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");
+      const { runDagStatus } = await import("./dag-runners-YQDHD7U6.js");
       await runDagStatus();
     } catch (e) {
       handleError(e);
@@ -1259,7 +1274,7 @@ function registerDagCommands(program) {
   });
   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");
+      const { runDagSimulateReorg } = await import("./dag-runners-YQDHD7U6.js");
       await runDagSimulateReorg({ depth: parseInt(options.depth) });
     } catch (e) {
       handleError(e);
@@ -1340,14 +1355,99 @@ async function runAccountsRealGenerate(options = {}) {
   };
 }
 
+// src/runners/accounts-balance-runner.ts
+import {
+  loadHardkasConfig as loadHardkasConfig2
+} from "@hardkas/config";
+import {
+  loadRealAccountStore as loadRealAccountStore2,
+  getRealDevAccount
+} from "@hardkas/accounts";
+import { JsonWrpcKaspaClient as JsonWrpcKaspaClient3 } from "@hardkas/kaspa-rpc";
+import { resolveRuntimeConfig } from "@hardkas/node-orchestrator";
+async function runAccountsBalance(options) {
+  let address = options.identifier;
+  let name = "Unknown";
+  const loadedConfig = await loadHardkasConfig2({});
+  const projectAccount = loadedConfig.config.accounts?.[options.identifier];
+  if (projectAccount) {
+    address = projectAccount.address ?? "";
+    name = options.identifier;
+  } else {
+    const store = await loadRealAccountStore2();
+    const realAccount = store ? getRealDevAccount(store, options.identifier) : null;
+    if (realAccount) {
+      address = realAccount.address ?? "";
+      name = realAccount.name;
+    }
+  }
+  const network = options.network ?? loadedConfig.config.defaultNetwork ?? "simnet";
+  let rpcUrl = options.url;
+  if (!rpcUrl) {
+    rpcUrl = resolveRuntimeConfig({ network }).rpcUrl;
+  }
+  const client = new JsonWrpcKaspaClient3({ rpcUrl });
+  try {
+    const balance = await client.getBalanceByAddress(address);
+    const utxos = await client.getUtxosByAddress(address);
+    return {
+      name,
+      address,
+      balanceSompi: balance.balanceSompi,
+      utxoCount: utxos.length,
+      network
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+// src/runners/accounts-fund-runner.ts
+import { loadHardkasConfig as loadHardkasConfig3 } from "@hardkas/config";
+import { resolveHardkasAccountAddress as resolveHardkasAccountAddress2 } from "@hardkas/accounts";
+import {
+  loadOrCreateLocalnetState as loadOrCreateLocalnetState2,
+  saveLocalnetState as saveLocalnetState2,
+  fundAddress
+} from "@hardkas/localnet";
+async function runAccountsFund(options) {
+  const loadedConfig = await loadHardkasConfig3({});
+  const address = resolveHardkasAccountAddress2(options.identifier, loadedConfig.config);
+  const networkId = loadedConfig.config.defaultNetwork || "simnet";
+  const allowedNetworks = ["simnet", "localnet", "dev", "simulated"];
+  if (!allowedNetworks.includes(networkId)) {
+    throw new Error(`Faucet/Funding is only allowed on development networks (${allowedNetworks.join(", ")}). Current network is: ${networkId}`);
+  }
+  if (networkId === "simulated" || networkId === "localnet") {
+    const state = await loadOrCreateLocalnetState2();
+    const amount = options.amountSompi || 1000n * 100000000n;
+    const newState = fundAddress(state, { address, amountSompi: amount });
+    await saveLocalnetState2(newState);
+    return {
+      success: true,
+      address,
+      amountSompi: amount,
+      mode: "simulated",
+      formatted: `Successfully funded ${options.identifier} (${address}) with ${Number(amount) / 1e8} KAS (Simulated)`
+    };
+  }
+  if (networkId === "simnet" || networkId === "dev") {
+    throw new Error(
+      `Funding for real simnet (Docker) via faucet requires a miner account. 
+Hint: Start your node with 'hardkas node start --miningaddr ${address}' to mine coins directly to this account.`
+    );
+  }
+  throw new Error(`Unsupported network for funding: ${networkId}`);
+}
+
 // 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 { loadHardkasConfig: loadHardkasConfig5 } = await import("@hardkas/config");
     const { listHardkasAccounts: listHardkasAccounts2, describeAccount } = await import("@hardkas/accounts");
     try {
-      const loaded = await loadHardkasConfig3(options.config ? { configPath: options.config } : {});
+      const loaded = await loadHardkasConfig5(options.config ? { configPath: options.config } : {});
       const accounts = listHardkasAccounts2(loaded.config);
       if (options.json) {
         console.log(JSON.stringify(accounts.map((a) => describeAccount(a)), null, 2));
@@ -1377,7 +1477,7 @@ function registerAccountsCommands(program) {
   });
   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 { runAccountsKeystoreImport } = await import("./accounts-keystore-runners-MCJIAGZ4.js");
       const result = await runAccountsKeystoreImport(options);
       if (options.json) console.log(JSON.stringify(result, null, 2));
       else console.log(result.formatted);
@@ -1386,26 +1486,28 @@ function registerAccountsCommands(program) {
       process.exitCode = 1;
     }
   });
-  realAccountsCmd.command("unlock <name>").description("Verify password for an encrypted account").action(async (name) => {
+  realAccountsCmd.command("unlock <name>").description(`Verify keystore access ${UI.maturity("internal")}`).action(async (name) => {
     try {
-      const { runAccountsKeystoreUnlock } = await import("./accounts-keystore-runners-CVRE6NVM.js");
+      const { runAccountsKeystoreUnlock } = await import("./accounts-keystore-runners-MCJIAGZ4.js");
       await runAccountsKeystoreUnlock({ name });
+      console.log(`
+  \u2713 Access to account '${name}' verified.`);
+      console.log(`  (Note: HardKAS CLI is stateless. Password will be required again for signing operations.)
+`);
     } 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("lock <name>").description(`[DEPRECATED] Lock an account ${UI.maturity("internal")}`).action(async (name) => {
+    console.log(`
+  \u2139 Account '${name}' session clear (redundant).`);
+    console.log(`    The CLI is already stateless. No secrets are stored in memory between commands.
+`);
   });
   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");
+      const { runAccountsKeystoreChangePassword } = await import("./accounts-keystore-runners-MCJIAGZ4.js");
       await runAccountsKeystoreChangePassword({ name });
     } catch (e) {
       handleError(e);
@@ -1426,6 +1528,34 @@ function registerAccountsCommands(program) {
       process.exitCode = 1;
     }
   });
+  accountsCmd.command("balance <identifier>").description("Show account balance").option("--network <name>", "Network name (simnet, localnet, etc.)").option("--url <rpc-url>", "Explicit RPC URL").option("--json", "Output as JSON", false).action(async (identifier, options) => {
+    try {
+      const result = await runAccountsBalance({ identifier, network: options.network ?? "simnet", url: options.url ?? "" });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`
+Account:  ${result.name}`);
+        console.log(`Address:  ${result.address}`);
+        console.log(`Balance:  ${Number(result.balanceSompi) / 1e8} KAS`);
+        console.log(`UTXOs:    ${result.utxoCount}`);
+        console.log(`Network:  ${result.network}`);
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  accountsCmd.command("fund <identifier>").description("Fund an account (Faucet)").option("--amount <kas>", "Amount in KAS to fund", "1000").action(async (identifier, options) => {
+    try {
+      const amountSompi = BigInt(parseFloat(options.amount) * 1e8);
+      const result = await runAccountsFund({ identifier, amountSompi });
+      console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
 }
 
 // src/runners/l2-networks-runner.ts
@@ -1523,10 +1653,11 @@ import {
   createIgraSignedId,
   assertValidIgraTxReceiptArtifact,
   listIgraTxReceiptArtifacts,
-  loadIgraTxReceiptArtifact
+  loadIgraTxReceiptArtifact,
+  calculateContentHash
 } from "@hardkas/artifacts";
 import {
-  loadRealAccountStore as loadRealAccountStore2,
+  loadRealAccountStore as loadRealAccountStore3,
   resolveRealAccountOrAddress
 } from "@hardkas/accounts";
 async function runL2TxBuild(options) {
@@ -1569,14 +1700,14 @@ async function runL2TxBuild(options) {
     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,
+    planId: "",
+    // Placeholder
     l2Network: profile.name,
     chainId,
     request: {
@@ -1592,6 +1723,10 @@ async function runL2TxBuild(options) {
     estimatedFeeWei,
     status: "built"
   };
+  const hash = calculateContentHash(artifact);
+  const planId = createIgraPlanId(hash);
+  artifact.planId = planId;
+  artifact.contentHash = hash;
   assertValidIgraTxPlanArtifact(artifact);
   const outDir = options.outDir || "plans";
   const sanitizedDir = path6.normalize(outDir).replace(/^(\.\.[\/\\])+/, "");
@@ -1647,7 +1782,7 @@ async function runL2TxSign(options) {
   }
   let accountInfo;
   if (options.account) {
-    const store = await loadRealAccountStore2();
+    const store = await loadRealAccountStore3();
     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}'`);
@@ -1686,14 +1821,14 @@ async function runL2TxSign(options) {
     }
     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,
+    signedId: "",
+    // Placeholder
     sourcePlanId: plan.planId,
     sourcePlanPath: options.planPath,
     l2Network: plan.l2Network,
@@ -1702,6 +1837,10 @@ async function runL2TxSign(options) {
     txHash: result.txHash || "unknown",
     status: "signed"
   };
+  const hash = calculateContentHash(artifact);
+  const signedId = createIgraSignedId(hash);
+  artifact.signedId = signedId;
+  artifact.contentHash = hash;
   assertValidIgraSignedTxArtifact(artifact);
   const outDir = options.outDir || "signed";
   const sanitizedDir = path6.normalize(outDir).replace(/^(\.\.[\/\\])+/, "");
@@ -1954,7 +2093,8 @@ import {
   writeArtifact as writeArtifact3,
   HARDKAS_VERSION as HARDKAS_VERSION3,
   ARTIFACT_SCHEMAS as ARTIFACT_SCHEMAS3,
-  createIgraDeployPlanId
+  createIgraDeployPlanId,
+  calculateContentHash as calculateContentHash2
 } from "@hardkas/artifacts";
 async function runL2ContractDeployPlan(options) {
   const networkName = options.network ?? "igra";
@@ -1999,14 +2139,14 @@ async function runL2ContractDeployPlan(options) {
     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,
+    planId: "",
+    // Placeholder
     l2Network: profile.name,
     chainId,
     txType: "contract-deploy",
@@ -2022,6 +2162,10 @@ async function runL2ContractDeployPlan(options) {
     estimatedFeeWei,
     status: "built"
   };
+  const hash = calculateContentHash2(artifact);
+  const planId = createIgraDeployPlanId(hash);
+  artifact.planId = planId;
+  artifact.contentHash = hash;
   assertValidIgraTxPlanArtifact2(artifact);
   const outDir = options.outDir || "plans";
   const sanitizedDir = path7.normalize(outDir).replace(/^(\.\.[\/\\])+/, "");
@@ -2402,10 +2546,49 @@ async function runNodeStatus(input) {
   };
 }
 
+// src/runners/node-stop-runner.ts
+import { DockerKaspadRunner as DockerKaspadRunner3 } from "@hardkas/node-runner";
+async function runNodeStop(input) {
+  const runner = new DockerKaspadRunner3(input.containerName ? { containerName: input.containerName } : {});
+  return runner.stop();
+}
+
+// src/runners/node-restart-runner.ts
+import { DockerKaspadRunner as DockerKaspadRunner4 } from "@hardkas/node-runner";
+async function runNodeRestart(input) {
+  const runner = new DockerKaspadRunner4({
+    ...input.containerName ? { containerName: input.containerName } : {},
+    ...input.image ? { image: input.image } : {}
+  });
+  const status = await runner.restart();
+  return {
+    status,
+    formatted: `Kaspa node restarted (Container: ${status.containerName})`
+  };
+}
+
+// src/runners/node-reset-runner.ts
+import { DockerKaspadRunner as DockerKaspadRunner5 } from "@hardkas/node-runner";
+async function runNodeReset(input) {
+  const runner = new DockerKaspadRunner5(input.containerName ? { containerName: input.containerName } : {});
+  const status = await runner.reset({ removeData: input.removeData !== false });
+  return {
+    status,
+    formatted: `Kaspa node reset complete. Data removed: ${input.removeData !== false}. Node is currently ${status.running ? "running" : "stopped"}.`
+  };
+}
+
+// src/runners/node-logs-runner.ts
+import { DockerKaspadRunner as DockerKaspadRunner6 } from "@hardkas/node-runner";
+async function runNodeLogs(input) {
+  const runner = new DockerKaspadRunner6(input.containerName ? { containerName: input.containerName } : {});
+  return await runner.logs(input.tail ? { tail: input.tail } : {}) ?? "";
+}
+
 // 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) => {
+  nodeCmd.command("start").description(`Start local node ${UI.maturity("stable")}`).option("--image <image>", "Docker image").action(async (options) => {
     try {
       const result = await runNodeStart(options);
       console.log(result.formatted);
@@ -2413,6 +2596,42 @@ function registerNodeCommands(program) {
       handleError(e);
     }
   });
+  nodeCmd.command("stop").description(`Stop local node ${UI.maturity("stable")}`).action(async () => {
+    try {
+      const result = await runNodeStop({});
+      UI.success(`Node stopped (Container: ${result.containerName})`);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  nodeCmd.command("restart").description(`Restart local node ${UI.maturity("stable")}`).action(async () => {
+    try {
+      const result = await runNodeRestart({});
+      console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+    }
+  });
+  nodeCmd.command("reset").description(`Stop node and remove all local chain data ${UI.maturity("preview")}`).option("--start", "Restart the node after reset", false).option("--yes", "Skip confirmation prompt", false).action(async (options) => {
+    try {
+      if (!options.yes) {
+        const confirmed = await UI.confirm("This will delete all local chain data. Are you sure?");
+        if (!confirmed) {
+          console.log("  Aborted.");
+          return;
+        }
+      }
+      const result = await runNodeReset({ removeData: true });
+      UI.success(result.formatted);
+      if (options.start) {
+        UI.info("Starting node...");
+        const startResult = await runNodeStart({});
+        console.log(startResult.formatted);
+      }
+    } catch (e) {
+      handleError(e);
+    }
+  });
   nodeCmd.command("status").description("Check node status").action(async () => {
     try {
       const result = await runNodeStatus({});
@@ -2421,15 +2640,25 @@ function registerNodeCommands(program) {
       handleError(e);
     }
   });
+  nodeCmd.command("logs").description(`View node logs ${UI.maturity("preview")}`).option("--tail <n>", "Number of lines to show", "100").option("--follow", "Follow log output", false).action(async (options) => {
+    try {
+      const result = await runNodeLogs({
+        tail: parseInt(options.tail, 10)
+      });
+      if (result) console.log(result);
+    } 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");
+    const { loadHardkasConfig: loadHardkasConfig5 } = await import("@hardkas/config");
     try {
-      const loaded = await loadHardkasConfig3(options.config ? { configPath: options.config } : {});
+      const loaded = await loadHardkasConfig5(options.config ? { configPath: options.config } : {});
       if (options.json) {
         console.log(JSON.stringify(loaded, null, 2));
         return;
@@ -2459,7 +2688,7 @@ function registerConfigCommands(program) {
 }
 
 // src/commands/misc.ts
-import { loadOrCreateLocalnetState as loadOrCreateLocalnetState2 } from "@hardkas/localnet";
+import { loadOrCreateLocalnetState as loadOrCreateLocalnetState3 } from "@hardkas/localnet";
 
 // src/runners/example-list-runner.ts
 import fs7 from "fs/promises";
@@ -2566,7 +2795,7 @@ function registerMiscCommands(program) {
   });
   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();
+      const state = await loadOrCreateLocalnetState3();
       UI.success("Local HardKAS devnet (simulated) is ready.");
       UI.info(`Network: ${state.networkId}`);
       UI.info(`Accounts: ${state.accounts.length}`);
@@ -2579,11 +2808,50 @@ function registerMiscCommands(program) {
 // 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");
+  const artifactsCmd = queryCmd.command("artifacts").description(`Query artifact store ${UI.maturity("stable")}`);
+  const storeCmd = queryCmd.command("store").description(`Manage query store index ${UI.maturity("alpha")}`);
+  storeCmd.command("doctor").description("Integrity and freshness check of the query store index").action(async () => {
+    try {
+      const engine = await getQueryEngine();
+      const report = await engine.backend.doctor();
+      console.log("\n  \u2550\u2550\u2550 Query Store Doctor \u2550\u2550\u2550\n");
+      console.log(`  Backend:      ${engine.backend.kind()}`);
+      console.log(`  Overall:      ${report.ok ? "\u2713 HEALTHY" : "\u2717 STALE / ISSUES"}`);
+      console.log(`  Last Indexed: ${report.lastIndexedAt || "never"}`);
+      console.log(`  Stale Rows:   ${report.staleArtifacts || 0}`);
+      console.log(`  Zombie Rows:  ${report.zombieArtifacts || 0}`);
+      console.log(`  Orphan Edges: ${report.orphanEdges || 0}`);
+      if (report.corruptedFiles?.length > 0) {
+        console.log("\n  Corrupted Files:");
+        for (const f of report.corruptedFiles) console.log(`    \u2717 ${f}`);
+      }
+      if (!report.ok) {
+        console.log("\n  Recommendation: Run 'hardkas query store rebuild' to fix issues.\n");
+      } else {
+        console.log("\n  Everything looks good.\n");
+      }
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+  storeCmd.command("rebuild").description("Force a complete rebuild of the query store index").action(async () => {
+    try {
+      console.log("\n  Rebuilding query store index...");
+      const engine = await getQueryEngine();
+      const start = Date.now();
+      await engine.backend.rebuild();
+      console.log(`  \u2713 Index rebuilt successfully in ${Date.now() - start}ms.
+`);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       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 });
@@ -2617,8 +2885,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({
         domain: "artifacts",
         op: "inspect",
@@ -2639,8 +2907,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({
         domain: "artifacts",
         op: "diff",
@@ -2658,11 +2926,11 @@ function registerQueryCommands(program) {
       process.exitCode = 1;
     }
   });
-  const lineageCmd = queryCmd.command("lineage").description("Traverse artifact lineage");
+  const lineageCmd = queryCmd.command("lineage").description(`Traverse artifact lineage ${UI.maturity("preview")}`);
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const explain = options.why ? "full" : options.explain === true ? "brief" : options.explain || false;
       const request = createQueryRequest({
         domain: "lineage",
@@ -2684,8 +2952,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const explain = options.why ? "full" : options.explain === true ? "brief" : options.explain || false;
       const request = createQueryRequest({
         domain: "lineage",
@@ -2707,8 +2975,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({
         domain: "lineage",
         op: "orphans",
@@ -2726,11 +2994,11 @@ function registerQueryCommands(program) {
       process.exitCode = 1;
     }
   });
-  const replayCmd = queryCmd.command("replay").description("Inspect replay history and divergence");
+  const replayCmd = queryCmd.command("replay").description(`Inspect replay history and divergence ${UI.maturity("preview")}`);
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       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) });
@@ -2748,8 +3016,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({ domain: "replay", op: "summary", params: { txId } });
       const result = await engine.execute(request);
       if (options.json) {
@@ -2765,8 +3033,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({
         domain: "replay",
         op: "divergences",
@@ -2786,8 +3054,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({
         domain: "replay",
         op: "invariants",
@@ -2806,11 +3074,11 @@ function registerQueryCommands(program) {
       process.exitCode = 1;
     }
   });
-  const dagCmd = queryCmd.command("dag").description("Query simulated DAG state (deterministic-light-model, NOT GHOSTDAG)");
+  const dagCmd = queryCmd.command("dag").description(`Query simulated DAG state ${UI.maturity("research")}`);
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       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);
@@ -2827,8 +3095,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const explain = options.explain === true ? "brief" : options.explain || false;
       const request = createQueryRequest({ domain: "dag", op: "displaced", explain });
       const result = await engine.execute(request);
@@ -2845,8 +3113,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       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);
@@ -2863,8 +3131,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({ domain: "dag", op: "sink-path" });
       const result = await engine.execute(request);
       if (options.json) {
@@ -2880,8 +3148,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const explain = options.explain === true ? "brief" : options.explain || false;
       const request = createQueryRequest({ domain: "dag", op: "anomalies", explain });
       const result = await engine.execute(request);
@@ -2898,8 +3166,8 @@ function registerQueryCommands(program) {
   });
   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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       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 });
@@ -2926,10 +3194,10 @@ function registerQueryCommands(program) {
       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) => {
+  queryCmd.command("tx <txId>").description(`Aggregate all data for a transaction ${UI.maturity("stable")}`).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 { createQueryRequest } = await import("@hardkas/query");
+      const engine = await getQueryEngine();
       const request = createQueryRequest({
         domain: "tx",
         op: "aggregate",
@@ -2960,9 +3228,12 @@ function printArtifactList(result) {
   }
   console.log(`
   queryHash: ${result.queryHash.slice(0, 16)}...`);
-  console.log(`  ${result.annotations.executionMs}ms | ${result.annotations.filesScanned ?? 0} files scanned
+  const backend = result.annotations.backendUsed || "unknown";
+  const freshness = result.annotations.freshness ? ` | ${result.annotations.freshness}` : "";
+  console.log(`  ${result.annotations.executionMs}ms | backend:${backend}${freshness} | ${result.annotations.filesScanned ?? 0} files scanned
 `);
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printInspectResult(result) {
   const item = result.items[0];
@@ -2988,7 +3259,8 @@ function printInspectResult(result) {
     for (const err of item.integrity.errors) console.log(`    \u2717 ${err}`);
   }
   console.log("");
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printDiffResult(result) {
   const diff = result.items[0];
@@ -3029,7 +3301,8 @@ function printLineageChain(result) {
     console.log(`${prefix} ${node.schema} [${node.contentHash.slice(0, 12)}...] ${node.networkId}/${node.mode}`);
   }
   console.log("");
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printTransitions(result) {
   console.log(`
@@ -3040,7 +3313,8 @@ function printTransitions(result) {
     console.log(`  ${marker} ${t.from.schema} \u2192 ${t.to.schema}  [${t.rule}]`);
   }
   console.log("");
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printOrphans(result) {
   if (result.total === 0) {
@@ -3056,7 +3330,8 @@ function printOrphans(result) {
     console.log(`    Reason: ${o.reason}
 `);
   }
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printReplayList(result) {
   console.log(`
@@ -3101,7 +3376,8 @@ function printDivergences(result) {
     console.log(`    Actual:   ${d.actual.slice(0, 60)}
 `);
   }
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printInvariants(result) {
   const inv = result.items[0];
@@ -3121,7 +3397,8 @@ function printInvariants(result) {
     for (const i of inv.issues) console.log(`    \u2717 ${i}`);
   }
   console.log("");
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printDagConflicts(result) {
   console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
@@ -3137,7 +3414,8 @@ function printDagConflicts(result) {
     for (const l of c.loserTxIds) console.log(`    \u2514\u2500 LOSER:  ${l.slice(0, 24)}...`);
     console.log("");
   }
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printDagDisplaced(result) {
   console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
@@ -3153,7 +3431,8 @@ function printDagDisplaced(result) {
     console.log(`    ${d.reason}
 `);
   }
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printDagHistory(result) {
   console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
@@ -3169,7 +3448,8 @@ function printDagHistory(result) {
     console.log(`  ${status.padEnd(10)} block:${e.blockId.slice(0, 12)}... daa:${e.daaScore} ${sinkPath}`);
   }
   console.log("");
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printSinkPath(result) {
   console.log("\n  \u26A0 DAG model: deterministic-light-model (NOT GHOSTDAG)\n");
@@ -3202,19 +3482,39 @@ function printDagAnomalies(result) {
     console.log(`  \u2717 [${a.kind}] ${a.description}
 `);
   }
-  if (result.explain) printExplainChains(result.explain);
+  if (result.explain) printExplain(result.explain);
+}
+function printExplain(explain) {
+  if (!explain) return;
+  console.log("  \u2500\u2500\u2500 Explain: Technical Diagnostics \u2500\u2500\u2500\n");
+  console.log(`  Backend:      ${explain.backend}`);
+  console.log(`  Freshness:    ${explain.freshness}`);
+  console.log(`  Rows Read:    ${explain.rowsRead}`);
+  console.log(`  Files Scan:   ${explain.scannedFiles}`);
+  if (explain.executionPlan && explain.executionPlan.length > 0) {
+    console.log(`  Plan:         ${explain.executionPlan.join(" \u2192 ")}`);
+  }
+  if (explain.warnings && explain.warnings.length > 0) {
+    console.log(`  Warnings:`);
+    for (const w of explain.warnings) console.log(`    \u26A0 ${w}`);
+  }
+  console.log("");
 }
-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) {
+function printWhy(why) {
+  if (!why || why.length === 0) return;
+  console.log("  \u2500\u2500\u2500 Why: Causal Analysis \u2500\u2500\u2500\n");
+  for (const block of why) {
+    console.log(`  Q: ${block.question}`);
+    console.log(`  A: ${block.answer}`);
+    for (const step of block.causalChain) {
       console.log(`    ${step.order}. ${step.assertion}`);
-      if (step.rule) console.log(`       Rule: ${step.rule}`);
+      console.log(`       Evidence: ${step.evidence}`);
+      if (step.rule) console.log(`       Rule:     ${step.rule}`);
     }
-    console.log(`  \u2192 ${chain.conclusion}`);
-    console.log(`  [model: ${chain.model}, confidence: ${chain.confidence}]
-`);
+    if (block.evidence && block.evidence.length > 0) {
+      console.log(`  Evidence Refs: ${block.evidence.map((e) => `${e.type}:${e.value.slice(0, 12)}...`).join(", ")}`);
+    }
+    console.log("");
   }
 }
 function printEventList(result) {
@@ -3229,7 +3529,8 @@ function printEventList(result) {
   queryHash: ${result.queryHash.slice(0, 16)}...`);
   console.log(`  ${result.annotations.executionMs}ms
 `);
-  if (result.explain) printExplainChains(result.explain);
+  printExplain(result.explain);
+  printWhy(result.why);
 }
 function printTxAggregate(result) {
   const agg = result.items[0];
@@ -3264,32 +3565,79 @@ function printTxAggregate(result) {
     }
   }
   console.log("");
-  if (result.explain) printExplainChains(result.explain);
+  if (result.explain) printExplain(result.explain);
+}
+async function getQueryEngine() {
+  const { QueryEngine } = await import("@hardkas/query");
+  return QueryEngine.create({
+    artifactDir: process.cwd()
+  });
 }
 
-// src/commands/test.ts
+// src/runners/test-runner.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();
+async function runTest(options) {
+  const { files, network, watch, json, reporter } = options;
+  if (!json) {
+    UI.header("HardKAS Test Runner");
+    UI.info(`Network: ${network}`);
+  }
+  let hardkas;
+  try {
+    hardkas = await Hardkas.open(".");
+  } catch (e) {
+    throw new Error("Could not find a valid HardKAS project in this directory.");
+  }
+  const searchPatterns = files.length > 0 ? files : ["test/**/*.test.ts", "tests/**/*.test.ts"];
+  if (!json) {
+    UI.info(`Searching for tests: ${searchPatterns.join(", ")}`);
+  }
+  try {
+    const { startVitest } = await import("vitest/node");
+    const vitestOptions = {
+      run: !watch,
+      watch: !!watch,
+      reporter: json ? "json" : reporter || "default",
+      globals: true,
+      environment: "node",
+      include: searchPatterns,
+      exclude: ["**/node_modules/**", "**/dist/**", "**/.hardkas/**"],
+      // Injected environment variables for tests to consume
+      env: {
+        HARDKAS_NETWORK: network,
+        HARDKAS_CWD: process.cwd()
       }
-      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)`);
+    };
+    const vitest = await startVitest("test", searchPatterns, vitestOptions);
+    if (!vitest) {
+      throw new Error("Failed to initialize test engine.");
+    }
+  } catch (e) {
+    const error = e;
+    if (error.code === "ERR_MODULE_NOT_FOUND" || error.message?.includes("vitest")) {
+      UI.warning("Vitest is not installed in this project.");
+      UI.info("Run 'pnpm add -D vitest' to enable real test execution.");
+      UI.divider();
+      UI.info("Fallback: No real tests were executed because the engine is missing.");
+      process.exit(1);
+    }
+    throw e;
+  }
+}
+
+// src/commands/test.ts
+function registerTestCommands(program) {
+  program.command("test [files...]").description(`Run HardKAS tests against localnet ${UI.maturity("stable")}`).option("--network <network>", "Network to test against", "simnet").option("--watch", "Watch for changes", false).option("--json", "Output results as JSON", false).option("--reporter <reporter>", "Reporter to use", "default").action(async (files, options) => {
+    try {
+      await runTest({
+        files,
+        network: options.network,
+        watch: options.watch,
+        json: options.json,
+        reporter: options.reporter
+      });
     } catch (e) {
-      console.error("Test execution failed:", e instanceof Error ? e.message : e);
+      handleError(e, "Test execution failed");
       process.exit(1);
     }
   });
@@ -3300,8 +3648,8 @@ 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 { loadHardkasConfig as loadHardkasConfig4 } from "@hardkas/config";
+import { JsonWrpcKaspaClient as JsonWrpcKaspaClient4 } 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 () => {
@@ -3321,7 +3669,7 @@ async function runDoctor() {
   UI.divider();
   UI.header("Configuration Analysis");
   try {
-    const loaded = await loadHardkasConfig2({ cwd: process.cwd() });
+    const loaded = await loadHardkasConfig4({ cwd: process.cwd() });
     UI.success(`Config found: ${pc.cyan(path10.basename(loaded.path || "unknown"))}`);
     UI.field("Default Network", loaded.config.defaultNetwork || "simnet");
   } catch (e) {
@@ -3330,15 +3678,15 @@ async function runDoctor() {
   UI.divider();
   UI.header("RPC Connectivity & Health");
   try {
-    const loaded = await loadHardkasConfig2({ cwd: process.cwd() });
+    const loaded = await loadHardkasConfig4({ 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 rpc = new JsonWrpcKaspaClient4({ rpcUrl });
     const info = await rpc.getInfo();
-    UI.success(`RPC Alive: ${pc.bold(info.networkId)}`);
+    UI.success(`RPC Alive: ${pc.bold(info.networkId || "active")}`);
     UI.field("Synced", info.isSynced ? pc.green("YES") : pc.yellow("NO"));
     if (info.serverVersion) UI.field("Version", info.serverVersion);
   } catch (e) {
@@ -3366,28 +3714,49 @@ async function runDoctor() {
   }
   UI.divider();
   UI.header("Query Store (SQLite) Status");
-  const dbPath = path10.join(hardkasDir, "query.db");
+  const dbPath = path10.join(hardkasDir, "store.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.success("Relational index (store.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.");
+      UI.warning("Database is empty. Run 'hardkas query store rebuild' to populate.");
     }
     store.disconnect();
   } catch (e) {
-    UI.error("Query Store Issues", "The SQLite database might be corrupt or inaccessible.");
+    UI.error("Query Store Issues", "The SQLite database might be corrupt or inaccessible. Run 'hardkas query store rebuild' to repair.");
   }
   UI.footer("Use 'hardkas query' for deep operational introspection.");
 }
 
+// src/commands/faucet.ts
+function registerFaucetCommand(program) {
+  program.command("faucet <identifier>").description(`Fund an account with KAS (Local only) ${UI.maturity("stable")}`).option("--amount <kas>", "Amount in KAS to fund", "1000").action(async (identifier, options) => {
+    try {
+      const amountSompi = BigInt(parseFloat(options.amount) * 1e8);
+      const result = await runAccountsFund({ identifier, amountSompi });
+      console.log(result.formatted);
+    } catch (e) {
+      handleError(e);
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/index.ts
-var HARDKAS_VERSION4 = "0.2.0-alpha";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import path11 from "path";
+var packageJsonPath = path11.resolve(
+  path11.dirname(fileURLToPath(import.meta.url)),
+  "../package.json"
+);
+var { version: HARDKAS_VERSION4 } = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 async function main() {
   const program = new Command();
   program.name("hardkas").description("HardKAS: Kaspa-native developer operating environment").version(HARDKAS_VERSION4);
@@ -3406,15 +3775,21 @@ async function main() {
   registerQueryCommands(program);
   registerTestCommands(program);
   registerDoctorCommand(program);
+  registerFaucetCommand(program);
   try {
     await program.parseAsync(process.argv);
   } catch (err) {
+    const { maskSecrets } = await import("@hardkas/core");
     console.error(`
-Error: ${err.message}`);
+Error: ${maskSecrets(err.message || String(err))}`);
     process.exit(1);
   }
 }
-main().catch((err) => {
-  console.error("Fatal error:", err);
+main().catch(async (err) => {
+  const { maskSecrets } = await import("@hardkas/core");
+  console.error("Fatal error:", maskSecrets(err.message || String(err)));
+  if (err.stack) {
+    console.error(maskSecrets(err.stack));
+  }
   process.exit(1);
 });