@hardkas/sdk 0.5.4-alpha → 0.6.0-alpha

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { defineHardkasConfig } from '@hardkas/config';
 import { KaspaRpcClient } from '@hardkas/kaspa-rpc';
 import { NetworkId } from '@hardkas/core';
 export { ArtifactId, HardkasError, KaspaAddress, LineageId, NetworkId, SOMPI_PER_KAS, TxId, formatSompi, parseKasToSompi } from '@hardkas/core';
-import { TxPlanArtifact, SignedTxArtifact, TxReceiptArtifact } from '@hardkas/artifacts';
+import { TxPlanArtifact, SignedTxArtifact, TxReceiptArtifact, HardkasArtifactBase, WorkflowArtifact } from '@hardkas/artifacts';
 export { ARTIFACT_SCHEMAS, HARDKAS_VERSION, SignedTxArtifact, TxPlanArtifact, TxReceiptArtifact, TxTraceArtifact, createTxPlanArtifact, writeArtifact } from '@hardkas/artifacts';
 import { HardkasAccount } from '@hardkas/accounts';
 export { signTxPlanArtifact } from '@hardkas/accounts';
@@ -52,9 +52,21 @@ declare class HardkasTx {
      */
     sign(plan: TxPlanArtifact, account?: HardkasAccount | string): Promise<SignedTxArtifact>;
     /**
-     * Sends a signed transaction.
+     * Simulates a transaction on the local state without broadcasting to a real Kaspa node.
+     * Modifies the local deterministic state and outputs receipt/trace artifacts.
      */
-    send(signed: SignedTxArtifact): Promise<TxReceiptArtifact>;
+    simulate(signedArtifact: SignedTxArtifact): Promise<{
+        receipt: TxReceiptArtifact;
+        receiptPath: string;
+        tracePath: string;
+    }>;
+    /**
+     * Sends a signed transaction to the real RPC network.
+     */
+    send(signedArtifact: SignedTxArtifact, url?: string): Promise<{
+        receipt: TxReceiptArtifact;
+        receiptPath: string;
+    }>;
 }
 
 /**
@@ -109,6 +121,113 @@ declare class HardkasLocalnet {
     reset(): Promise<void>;
 }
 
+interface ReplayVerifyOptions {
+    path?: string;
+    workflowId?: string;
+}
+interface ReplayVerifyResult {
+    passed: boolean;
+    artifactsScanned: number;
+    lineage: "valid" | "invalid";
+    determinism: "verified" | "failed";
+    contamination: "clean" | "contaminated";
+    report: any;
+    error?: string;
+}
+declare class HardkasReplay {
+    private sdk;
+    constructor(sdk: Hardkas);
+    /**
+     * Verifies the deterministic artifact lineage of a transaction replay
+     * against the mathematically reconstructed localnet state.
+     */
+    verify(options: ReplayVerifyOptions): Promise<ReplayVerifyResult>;
+}
+
+/**
+ * Deterministic Workspace Abstraction.
+ * Encapsulates all filesystem boundary interactions and isolates paths
+ * from the global process.cwd(), ensuring agent/script replayability.
+ */
+declare class HardkasWorkspace {
+    readonly root: string;
+    constructor(cwd: string);
+    get hardkasDir(): string;
+    get artifactsDir(): string;
+    get localnetStatePath(): string;
+    get keystoreDir(): string;
+    /**
+     * Safely resolves a path relative to the workspace root.
+     */
+    resolvePath(...segments: string[]): string;
+    /**
+     * Safely builds a relative path from the workspace root to the target.
+     */
+    relativeFromRoot(absolutePath: string): string;
+    /**
+     * Ensures the core .hardkas directory exists.
+     */
+    ensureHardkasDir(): void;
+}
+
+interface WriteArtifactOptions {
+    /**
+     * Explicitly override the canonical artifacts directory.
+     * By default, it writes to sdk.workspace.artifactsDir.
+     */
+    outputDir?: string;
+    /**
+     * Explicitly override the default filename.
+     * By default, it generates `${schema}-${contentHash}.json`
+     */
+    fileName?: string;
+    /**
+     * If true, verifies integrity and schema but does not touch the filesystem.
+     * Useful for Agent planning or previews.
+     */
+    dryRun?: boolean;
+    /** Telemetry for Event Sourcing */
+    workflowId?: string;
+    correlationId?: string;
+    networkId?: string;
+}
+interface WriteArtifactResult {
+    absolutePath?: string;
+    dryRun: boolean;
+    contentHash: string;
+}
+/**
+ * Deterministic Artifact I/O boundary.
+ */
+declare class HardkasArtifactsManager {
+    private workspace;
+    constructor(workspace: HardkasWorkspace);
+    /**
+     * Writes a valid artifact to disk (canonical or custom path).
+     */
+    write(artifact: HardkasArtifactBase, options?: WriteArtifactOptions): Promise<WriteArtifactResult>;
+    /**
+     * Reads an artifact by path or ID/hash from the workspace.
+     */
+    read(id: string): Promise<any>;
+}
+
+interface WorkflowRunOptions {
+    steps: Array<{
+        type: string;
+        [key: string]: any;
+    }>;
+    dryRun?: boolean;
+}
+declare class HardkasWorkflow {
+    private readonly sdk;
+    constructor(sdk: Hardkas);
+    /**
+     * Executes a sequence of declarative steps and returns a definitive WorkflowArtifact.
+     */
+    run(options: WorkflowRunOptions): Promise<WorkflowArtifact>;
+}
+
 interface TaskArgs {
     [key: string]: string | boolean | undefined;
 }
@@ -129,6 +248,13 @@ declare const defineTask: {
 interface HardkasOptions {
     cwd?: string;
     configPath?: string;
+    mode?: "developer" | "agent";
+    policy?: {
+        allowNetwork?: boolean;
+        allowMainnet?: boolean;
+        allowExternalWallet?: boolean;
+        requireDryRun?: boolean;
+    };
 }
 /**
  * HardKAS SDK - Main Entry Point
@@ -138,11 +264,17 @@ interface HardkasOptions {
  */
 declare class Hardkas {
     readonly config: LoadedHardkasConfig;
+    readonly workspace: HardkasWorkspace;
+    readonly artifacts: HardkasArtifactsManager;
     readonly accounts: HardkasAccounts;
     readonly tx: HardkasTx;
     readonly l2: HardkasL2;
     readonly query: HardkasQuery;
     readonly localnet: HardkasLocalnet;
+    readonly replay: HardkasReplay;
+    readonly workflow: HardkasWorkflow;
+    readonly mode: "developer" | "agent";
+    readonly policy: Required<NonNullable<HardkasOptions["policy"]>>;
     readonly rpc: KaspaRpcClient;
     private constructor();
     private resolveRpcUrl;
@@ -160,6 +292,11 @@ declare class Hardkas {
     get network(): NetworkId;
     get sdkConfig(): _hardkas_config.HardkasConfig;
     get cwd(): string;
+    /**
+     * Validates an action against the active security policy.
+     * Throws HardkasError if the policy is violated.
+     */
+    enforcePolicy(action: "network" | "mainnet" | "external-wallet" | "mutation", context?: string): void;
 }
 
-export { Hardkas, HardkasAccounts, HardkasL2, HardkasLocalnet, type HardkasOptions, HardkasQuery, HardkasTx, type TaskArgs, type TaskContext, defineTask };
+export { Hardkas, HardkasAccounts, HardkasArtifactsManager, HardkasL2, HardkasLocalnet, type HardkasOptions, HardkasQuery, HardkasReplay, HardkasTx, HardkasWorkspace, type TaskArgs, type TaskContext, defineTask };

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/index.ts
 import { loadHardkasConfig as loadConfig } from "@hardkas/config";
 import { JsonWrpcKaspaClient } from "@hardkas/kaspa-rpc";
+import { HardkasError as HardkasError2 } from "@hardkas/core";
 
 // src/accounts.ts
 import {
@@ -37,17 +38,22 @@ var HardkasAccounts = class {
 };
 
 // src/tx.ts
+import { systemRuntimeContext } from "@hardkas/core";
 import {
   buildPaymentPlan
 } from "@hardkas/tx-builder";
 import {
   HARDKAS_VERSION,
+  ARTIFACT_SCHEMAS,
+  ARTIFACT_VERSION,
+  CURRENT_HASH_VERSION,
   getBroadcastableSignedTransaction,
   writeArtifact,
   getDefaultReceiptPath,
   createTxPlanArtifact,
   calculateContentHash
 } from "@hardkas/artifacts";
+import { coreEvents } from "@hardkas/core";
 import { signTxPlanArtifact } from "@hardkas/accounts";
 import { parseKasToSompi } from "@hardkas/core";
 var HardkasTx = class {
@@ -63,7 +69,7 @@ var HardkasTx = class {
     const toAccount = typeof options.to === "string" ? await this.sdk.accounts.resolve(options.to) : options.to;
     if (!fromAccount.address) throw new Error(`From account ${fromAccount.name} has no address.`);
     if (!toAccount.address) throw new Error(`To account ${toAccount.name} has no address.`);
-    const amountSompi = typeof options.amount === "string" ? parseKasToSompi(options.amount) : options.amount;
+    const amountSompi = typeof options.amount === "string" ? parseKasToSompi(options.amount) : typeof options.amount === "number" ? BigInt(options.amount) : options.amount;
     const rpcUtxos = await this.sdk.rpc.getUtxosByAddress(fromAccount.address);
     const builderUtxos = rpcUtxos.map((u) => ({
       outpoint: {
@@ -96,7 +102,8 @@ var HardkasTx = class {
         address: toAccount.address
       },
       amountSompi,
-      plan: builderPlan
+      plan: builderPlan,
+      ctx: systemRuntimeContext
     });
   }
   /**
@@ -119,36 +126,130 @@ var HardkasTx = class {
     });
   }
   /**
-   * Sends a signed transaction.
+   * Simulates a transaction on the local state without broadcasting to a real Kaspa node.
+   * Modifies the local deterministic state and outputs receipt/trace artifacts.
    */
-  async send(signed) {
-    const broadcastable = getBroadcastableSignedTransaction(signed);
-    const result = await this.sdk.rpc.submitTransaction(broadcastable.rawTransaction);
-    const txId = result.transactionId;
-    if (!txId) throw new Error("Broadcast failed: RPC returned no transaction ID.");
-    const receipt = {
-      schema: "hardkas.txReceipt",
+  async simulate(signedArtifact) {
+    const {
+      loadOrCreateLocalnetState,
+      saveLocalnetState,
+      applySimulatedPayment,
+      saveSimulatedReceipt,
+      saveSimulatedTrace
+    } = await import("@hardkas/localnet");
+    const path4 = await import("path");
+    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)
+    }, systemRuntimeContext);
+    coreEvents.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 receiptBase = {
+      schema: ARTIFACT_SCHEMAS.TX_RECEIPT,
       hardkasVersion: HARDKAS_VERSION,
-      version: "1.0.0-alpha",
-      networkId: signed.networkId,
-      mode: signed.mode,
-      status: "accepted",
+      version: ARTIFACT_VERSION,
+      hashVersion: CURRENT_HASH_VERSION,
+      networkId: this.sdk.network,
+      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?.toString() || "0",
+      changeSompi: simResult.receipt.changeSompi?.toString() || "0",
+      spentUtxoIds: simResult.receipt.spentUtxoIds,
+      createdUtxoIds: simResult.receipt.createdUtxoIds,
+      daaScore: simResult.receipt.daaScore?.toString() || "0",
+      preStateHash: simResult.receipt.preStateHash,
+      postStateHash: simResult.receipt.postStateHash,
+      submittedAt: simResult.receipt.createdAt,
+      confirmedAt: simResult.receipt.createdAt,
+      rpcUrl: "simulated://local"
+    };
+    receiptBase.contentHash = calculateContentHash(receiptBase, CURRENT_HASH_VERSION);
+    const receipt = receiptBase;
+    const traceSteps = events.map((ev) => ({
+      phase: ev.phase || ev.message || "unknown",
+      status: ev.type.includes("completed") ? "completed" : ev.type.includes("failed") ? "failed" : "started",
+      timestamp: new Date(ev.timestamp).toISOString(),
+      details: ev.type === "note" ? { message: ev.message } : void 0
+    }));
+    const traceBase = {
+      schema: ARTIFACT_SCHEMAS.TX_TRACE,
+      hardkasVersion: HARDKAS_VERSION,
+      version: ARTIFACT_VERSION,
+      hashVersion: CURRENT_HASH_VERSION,
+      createdAt: receipt.createdAt,
+      txId: receipt.txId,
+      mode: "simulated",
+      networkId: this.sdk.network,
+      steps: traceSteps
+    };
+    traceBase.contentHash = calculateContentHash(traceBase, CURRENT_HASH_VERSION);
+    const tracePath = await saveSimulatedTrace({
+      ...traceBase,
+      events,
+      receiptPath
+    });
+    receipt.tracePath = tracePath;
+    return {
+      receipt,
+      receiptPath,
+      tracePath
+    };
+  }
+  /**
+   * Sends a signed transaction to the real RPC network.
+   */
+  async send(signedArtifact, url) {
+    const broadcastable = getBroadcastableSignedTransaction(signedArtifact);
+    const broadcastRecord = broadcastable.rawTransaction;
+    const txId = broadcastRecord.id || "unknown";
+    coreEvents.normalizeAndEmit({
+      kind: "workflow.submitted",
       txId,
-      from: {
-        address: signed.from.address
-      },
-      to: {
-        address: signed.to.address
-      },
-      amountSompi: String(signed.amountSompi),
-      feeSompi: String(signed.estimatedFeeSompi || "0")
+      endpoint: url || "real"
+    });
+    const result = await this.sdk.rpc.submitTransaction(broadcastable.rawTransaction);
+    const realReceiptBase = {
+      schema: ARTIFACT_SCHEMAS.TX_RECEIPT,
+      hardkasVersion: HARDKAS_VERSION,
+      version: ARTIFACT_VERSION,
+      hashVersion: CURRENT_HASH_VERSION,
+      networkId: this.sdk.network,
+      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(),
+      ...url ? { rpcUrl: url } : {}
     };
-    receipt.contentHash = calculateContentHash(receipt);
-    const receiptPath = getDefaultReceiptPath(txId, this.sdk.config.cwd);
+    realReceiptBase.contentHash = calculateContentHash(realReceiptBase, CURRENT_HASH_VERSION);
+    const receipt = realReceiptBase;
+    const receiptPath = getDefaultReceiptPath(receipt.txId, this.sdk.config.cwd);
     await writeArtifact(receiptPath, receipt);
     return {
-      ...receipt,
+      receipt,
       receiptPath
     };
   }
@@ -226,6 +327,451 @@ var HardkasLocalnet = class {
   }
 };
 
+// src/replay.ts
+import fs from "fs";
+import path from "path";
+import {
+  readTxPlanArtifact,
+  readTxReceiptArtifact as readTxReceiptArtifact2,
+  verifyArtifactIntegrity,
+  writeArtifact as writeArtifact2
+} from "@hardkas/artifacts";
+var HardkasReplay = class {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+  sdk;
+  /**
+   * Verifies the deterministic artifact lineage of a transaction replay 
+   * against the mathematically reconstructed localnet state.
+   */
+  async verify(options) {
+    const artifactDir = options.path ? path.resolve(this.sdk.config.cwd, options.path) : this.sdk.config.cwd;
+    if (options.path && !fs.existsSync(path.join(artifactDir, "hardkas.config.ts"))) {
+      throw new Error(`Workspace not found at ${options.path}`);
+    }
+    const planPath = path.join(artifactDir, "tx-plan.json");
+    const receiptPath = path.join(artifactDir, "tx-receipt.json");
+    const canonicalDirs = [
+      path.join(artifactDir, ".hardkas", "receipts"),
+      path.join(artifactDir, ".hardkas", "traces"),
+      path.join(artifactDir, ".hardkas", "deployments")
+    ];
+    const files = [];
+    for (const dir of canonicalDirs) {
+      if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
+        const list = fs.readdirSync(dir);
+        for (const f of list) {
+          if (f.endsWith(".json")) {
+            files.push(path.join(dir, f));
+          }
+        }
+      }
+    }
+    if (fs.existsSync(artifactDir) && fs.statSync(artifactDir).isDirectory()) {
+      const rootFiles = fs.readdirSync(artifactDir);
+      for (const f of rootFiles) {
+        if (f.startsWith("tx-") && f.endsWith(".json")) {
+          files.push(path.join(artifactDir, f));
+        }
+      }
+    }
+    let artifactCount = 0;
+    let lineageOk = true;
+    let determinismOk = true;
+    let contaminationOk = true;
+    const isContaminated = (artifact) => {
+      if (artifact.networkId && artifact.networkId !== "simnet" && artifact.networkId !== "simulated") {
+        const str = JSON.stringify(artifact);
+        if (str.includes("kaspa:sim_")) {
+          return true;
+        }
+      }
+      return false;
+    };
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(file, "utf-8");
+        const json = JSON.parse(content);
+        if (json && json.schema && typeof json.schema === "string" && json.schema.startsWith("hardkas.")) {
+          artifactCount++;
+          if (isContaminated(json)) contaminationOk = false;
+          const isCoreArtifact = ["hardkas.txPlan", "hardkas.signedTx", "hardkas.txReceipt", "hardkas.snapshot"].includes(json.schema);
+          if (isCoreArtifact) {
+            const integrity = await verifyArtifactIntegrity(json);
+            if (!integrity.ok) determinismOk = false;
+          }
+        } else {
+          lineageOk = false;
+        }
+      } catch (e) {
+        lineageOk = false;
+        determinismOk = false;
+      }
+    }
+    let plan;
+    let receipt;
+    let verifyErrorMsg;
+    let report = null;
+    if (options.workflowId) {
+      try {
+        const wfArtifactPath = fs.readdirSync(this.sdk.workspace.artifactsDir).find((f) => f.includes(options.workflowId) && f.endsWith(".json"));
+        if (!wfArtifactPath) throw new Error("Workflow artifact not found");
+        const wfArtifactStr = fs.readFileSync(path.join(this.sdk.workspace.artifactsDir, wfArtifactPath), "utf-8");
+        const wfArtifact = JSON.parse(wfArtifactStr);
+        if (wfArtifact.schema !== "hardkas.workflow.v1") {
+          throw new Error(`Artifact ${options.workflowId} is not a workflow artifact`);
+        }
+        const childArtifacts = wfArtifact.producedArtifacts || [];
+        for (const childId of childArtifacts) {
+          const childFile = fs.readdirSync(this.sdk.workspace.artifactsDir).find((f) => f.includes(childId) && f.endsWith(".json"));
+          if (!childFile) throw new Error(`Child artifact ${childId} not found`);
+          const childStr = fs.readFileSync(path.join(this.sdk.workspace.artifactsDir, childFile), "utf-8");
+          const child = JSON.parse(childStr);
+          const integrity = await verifyArtifactIntegrity(child);
+          if (!integrity.ok) {
+            determinismOk = false;
+            verifyErrorMsg = `Child artifact ${childId} failed cryptographic determinism check: ${JSON.stringify(integrity.issues)}`;
+            break;
+          }
+          if (isContaminated(child)) {
+            contaminationOk = false;
+            verifyErrorMsg = `Child artifact ${childId} is contaminated with simulated signatures in a real run`;
+            break;
+          }
+          artifactCount++;
+        }
+        report = { invariantsOk: determinismOk && contaminationOk };
+      } catch (e) {
+        verifyErrorMsg = `Workflow Replay failed: ${e.message}`;
+        lineageOk = false;
+        determinismOk = false;
+      }
+    } else if (options.path) {
+      try {
+        if (!fs.existsSync(planPath)) throw new Error(`Transaction plan artifact is missing at: ${planPath}`);
+        if (!fs.existsSync(receiptPath)) throw new Error(`Transaction receipt artifact is missing at: ${receiptPath}`);
+        plan = await readTxPlanArtifact(planPath);
+        receipt = await readTxReceiptArtifact2(receiptPath);
+      } catch (err) {
+        verifyErrorMsg = err.message;
+      }
+      if (!verifyErrorMsg && plan && receipt) {
+        try {
+          const { loadOrCreateLocalnetState, reconstructStateAtDaa, verifyReplay } = await import("@hardkas/localnet");
+          const { systemRuntimeContext: systemRuntimeContext2 } = await import("@hardkas/core");
+          let state = await loadOrCreateLocalnetState();
+          if (receipt.mode === "simulated" && receipt.daaScore) {
+            const receiptDaa = BigInt(receipt.daaScore);
+            const targetDaa = receiptDaa - 1n;
+            state = reconstructStateAtDaa(state, targetDaa);
+          }
+          report = verifyReplay(state, plan, receipt, systemRuntimeContext2);
+          const reportFilename = `${(/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-")}-${receipt.txId}.replay.json`;
+          const reportPath = path.join(this.sdk.workspace.artifactsDir, reportFilename);
+          await writeArtifact2(reportPath, report);
+        } catch (err) {
+          verifyErrorMsg = `Replay execution failed: ${err.message}`;
+        }
+      }
+    } else {
+      verifyErrorMsg = "No path or workflowId provided for replay verification";
+    }
+    const invariantsOk = report ? report.invariantsOk : false;
+    const passed = lineageOk && determinismOk && contaminationOk && invariantsOk && !verifyErrorMsg;
+    return {
+      passed,
+      artifactsScanned: artifactCount,
+      lineage: lineageOk ? "valid" : "invalid",
+      determinism: determinismOk ? "verified" : "failed",
+      contamination: contaminationOk ? "clean" : "contaminated",
+      report,
+      ...verifyErrorMsg ? { error: verifyErrorMsg } : {}
+    };
+  }
+};
+
+// src/workspace.ts
+import path2 from "path";
+import fs2 from "fs";
+var HardkasWorkspace = class {
+  root;
+  constructor(cwd) {
+    this.root = path2.resolve(cwd);
+  }
+  get hardkasDir() {
+    return path2.join(this.root, ".hardkas");
+  }
+  get artifactsDir() {
+    return path2.join(this.hardkasDir, "artifacts");
+  }
+  get localnetStatePath() {
+    return path2.join(this.hardkasDir, "localnet-state.json");
+  }
+  get keystoreDir() {
+    return path2.join(this.hardkasDir, "keystore");
+  }
+  /**
+   * Safely resolves a path relative to the workspace root.
+   */
+  resolvePath(...segments) {
+    return path2.resolve(this.root, ...segments);
+  }
+  /**
+   * Safely builds a relative path from the workspace root to the target.
+   */
+  relativeFromRoot(absolutePath) {
+    return path2.relative(this.root, absolutePath);
+  }
+  /**
+   * Ensures the core .hardkas directory exists.
+   */
+  ensureHardkasDir() {
+    if (!fs2.existsSync(this.hardkasDir)) {
+      fs2.mkdirSync(this.hardkasDir, { recursive: true });
+    }
+  }
+};
+
+// src/artifacts-manager.ts
+import path3 from "path";
+import fs3 from "fs";
+var HardkasArtifactsManager = class {
+  constructor(workspace) {
+    this.workspace = workspace;
+  }
+  workspace;
+  /**
+   * Writes a valid artifact to disk (canonical or custom path).
+   */
+  async write(artifact, options = {}) {
+    const record = artifact;
+    const hash = record.contentHash || "unknown";
+    if (options.dryRun) {
+      return {
+        dryRun: true,
+        contentHash: hash
+      };
+    }
+    const outputDir = options.outputDir || this.workspace.artifactsDir;
+    if (!fs3.existsSync(outputDir)) {
+      fs3.mkdirSync(outputDir, { recursive: true });
+    }
+    const schema = record.schema || "artifact";
+    const shortSchema = schema.replace("hardkas.", "");
+    const fileName = options.fileName || `${shortSchema}-${hash}.json`;
+    const absolutePath = path3.join(outputDir, fileName);
+    const { writeArtifact: writeArtifact4 } = await import("@hardkas/artifacts");
+    await writeArtifact4(absolutePath, artifact);
+    const { coreEvents: coreEvents2, createEventEnvelope } = await import("@hardkas/core");
+    const wId = options.workflowId || "wf_unknown_standalone";
+    const cId = options.correlationId || wId;
+    const netId = options.networkId || record.networkId || "unknown";
+    const artifactId = record.artifactId || hash;
+    coreEvents2.emit(createEventEnvelope({
+      kind: "artifact.written",
+      domain: "integrity",
+      workflowId: wId,
+      correlationId: cId,
+      networkId: netId,
+      payload: { artifactId, path: absolutePath },
+      sequenceNumber: 1,
+      globalOffset: 0,
+      sourceSubsystem: "sdk:artifacts-manager",
+      artifactId
+    }));
+    return {
+      absolutePath,
+      dryRun: false,
+      contentHash: hash
+    };
+  }
+  /**
+   * Reads an artifact by path or ID/hash from the workspace.
+   */
+  async read(id) {
+    const { readArtifact } = await import("@hardkas/artifacts");
+    let filePath = id;
+    if (!fs3.existsSync(filePath)) {
+      filePath = path3.join(this.workspace.artifactsDir, `${id}.json`);
+      if (!fs3.existsSync(filePath)) {
+        if (fs3.existsSync(this.workspace.artifactsDir)) {
+          const files = fs3.readdirSync(this.workspace.artifactsDir);
+          const found = files.find((f) => f.includes(id) || f.endsWith(`${id}.json`));
+          if (found) {
+            filePath = path3.join(this.workspace.artifactsDir, found);
+          } else {
+            throw new Error(`Artifact ${id} not found in workspace.`);
+          }
+        } else {
+          throw new Error(`Artifact ${id} not found in workspace.`);
+        }
+      }
+    }
+    return readArtifact(filePath);
+  }
+};
+
+// src/workflow.ts
+import { HARDKAS_VERSION as HARDKAS_VERSION2 } from "@hardkas/artifacts";
+import { HardkasError } from "@hardkas/core";
+var HardkasWorkflow = class {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+  sdk;
+  /**
+   * Executes a sequence of declarative steps and returns a definitive WorkflowArtifact.
+   */
+  async run(options) {
+    const { calculateContentHash: calculateContentHash2 } = await import("@hardkas/artifacts");
+    const intentPayload = {
+      type: "hardkas.workflow.intent",
+      schemaVersion: "v1",
+      workflowSpec: options.steps,
+      normalizedInputs: {},
+      parentArtifacts: [],
+      // In v1, workflows do not accept explicit parent inputs yet
+      policySnapshot: {
+        allowNetwork: this.sdk.policy.allowNetwork,
+        allowMainnet: this.sdk.policy.allowMainnet,
+        allowExternalWallet: this.sdk.policy.allowExternalWallet,
+        requireDryRun: this.sdk.policy.requireDryRun
+      },
+      capabilitySnapshot: {
+        mode: this.sdk.mode,
+        network: this.sdk.network
+      },
+      runtimeVersion: HARDKAS_VERSION2,
+      workspaceSchemaVersion: "hardkas.workflow.v1"
+    };
+    const intentHash = calculateContentHash2(intentPayload);
+    const workflowId = `wf_${intentHash.slice(0, 16)}`;
+    const artifactSteps = [];
+    const producedArtifacts = [];
+    const parentArtifacts = [];
+    const generationStart = Date.now().toString();
+    let status = "completed";
+    let errorEnvelope = void 0;
+    let lastPlan = null;
+    let lastSigned = null;
+    for (const step of options.steps) {
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      try {
+        if (step.type === "simulate-failure") {
+          if (this.sdk.mode === "agent") {
+            throw new HardkasError("POLICY_DENIED", "simulate-failure is strictly prohibited in agent mode");
+          }
+          throw new HardkasError("MOCKED_FAIL", "Simulated failure for contract tests");
+        }
+        let producedArtifactId = void 0;
+        if (step.type === "network.switch") {
+          const targetNetwork = step.args?.network || step.network;
+          if (targetNetwork === "mainnet") {
+            this.sdk.enforcePolicy("mainnet", "Workflow requested network switch to mainnet");
+          }
+        } else if (step.type === "tx.plan") {
+          this.sdk.enforcePolicy("network", "Workflow requested transaction planning");
+          lastPlan = await this.sdk.tx.plan({
+            from: step.args?.from || step.from,
+            to: step.args?.to || step.to,
+            amount: step.args?.amount || step.amount
+          });
+          if (!options.dryRun) {
+            await this.sdk.artifacts.write(lastPlan);
+          }
+          const planRecord = lastPlan;
+          producedArtifactId = lastPlan.artifactId || planRecord.contentHash;
+          if (producedArtifactId) producedArtifacts.push(producedArtifactId);
+        } else if (step.type === "tx.simulate" || step.type === "tx.send") {
+          if (!lastPlan) throw new Error("Cannot sign or send without a prior tx.plan step");
+          if (step.type === "tx.send") {
+            this.sdk.enforcePolicy("mutation", "Workflow requested real broadcast via tx.send");
+          }
+          lastSigned = await this.sdk.tx.sign(lastPlan);
+          if (!options.dryRun) {
+            await this.sdk.artifacts.write(lastSigned);
+          }
+          const signedRecord = lastSigned;
+          const signedId = lastSigned.artifactId || signedRecord.contentHash;
+          if (signedId) producedArtifacts.push(signedId);
+          if (step.type === "tx.simulate") {
+            const { receipt } = await this.sdk.tx.simulate(lastSigned);
+            if (!options.dryRun) await this.sdk.artifacts.write(receipt);
+            const receiptRecord = receipt;
+            producedArtifactId = receiptRecord.artifactId || receiptRecord.contentHash;
+            if (producedArtifactId) producedArtifacts.push(producedArtifactId);
+          } else {
+            const { receipt } = await this.sdk.tx.send(lastSigned);
+            if (!options.dryRun) await this.sdk.artifacts.write(receipt);
+            const receiptRecord = receipt;
+            producedArtifactId = receiptRecord.artifactId || receiptRecord.contentHash;
+            if (producedArtifactId) producedArtifacts.push(producedArtifactId);
+          }
+        }
+        const stepRecord = {
+          type: step.type,
+          status: "success",
+          startedAt,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        if (producedArtifactId) stepRecord.producedArtifactId = producedArtifactId;
+        artifactSteps.push(stepRecord);
+      } catch (e) {
+        console.error("DEBUG WORKFLOW ERROR:", e.stack);
+        status = "failed";
+        errorEnvelope = {
+          code: e.code || "WORKFLOW_STEP_FAILED",
+          message: e.message,
+          redacted: false
+        };
+        artifactSteps.push({
+          type: step.type,
+          status: "failed",
+          startedAt,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          error: e.message
+        });
+        break;
+      }
+    }
+    const executionMode = this.sdk.network === "simulated" ? "simulated" : "real";
+    const artifact = {
+      schema: "hardkas.workflow.v1",
+      version: "1.0.0-alpha",
+      hardkasVersion: HARDKAS_VERSION2,
+      networkId: this.sdk.network,
+      mode: executionMode,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      workflowId,
+      artifactId: workflowId,
+      status,
+      steps: artifactSteps,
+      parentArtifacts,
+      producedArtifacts,
+      generationRange: {
+        start: generationStart,
+        end: Date.now().toString()
+      },
+      policy: {
+        allowNetwork: this.sdk.policy.allowNetwork,
+        allowMainnet: this.sdk.policy.allowMainnet,
+        allowExternalWallet: this.sdk.policy.allowExternalWallet,
+        requireDryRun: this.sdk.policy.requireDryRun
+      }
+    };
+    if (errorEnvelope) {
+      artifact.errorEnvelope = errorEnvelope;
+    }
+    artifact.contentHash = calculateContentHash2(artifact, 1);
+    if (!options.dryRun) {
+      this.sdk.enforcePolicy("mutation", "Workflow Runtime saving artifact");
+      await this.sdk.artifacts.write(artifact, { fileName: `workflow.v1-${workflowId}.json` });
+    }
+    return artifact;
+  }
+};
+
 // src/index.ts
 import { defineHardkasConfig as defineHardkasConfig2 } from "@hardkas/config";
 
@@ -261,35 +807,52 @@ var defineTask = taskRegistry.defineTask.bind(taskRegistry);
 import { buildPaymentPlan as buildPaymentPlan2 } from "@hardkas/tx-builder";
 import { signTxPlanArtifact as signTxPlanArtifact2 } from "@hardkas/accounts";
 import {
-  writeArtifact as writeArtifact2,
+  writeArtifact as writeArtifact3,
   createTxPlanArtifact as createTxPlanArtifact2,
-  ARTIFACT_SCHEMAS,
-  HARDKAS_VERSION as HARDKAS_VERSION2
+  ARTIFACT_SCHEMAS as ARTIFACT_SCHEMAS2,
+  HARDKAS_VERSION as HARDKAS_VERSION3
 } from "@hardkas/artifacts";
 import {
   SOMPI_PER_KAS,
-  HardkasError,
+  HardkasError as HardkasError3,
   parseKasToSompi as parseKasToSompi2,
   formatSompi as formatSompi2
 } from "@hardkas/core";
 var Hardkas = class _Hardkas {
-  constructor(config, rpc) {
+  constructor(config, options, rpc) {
     this.config = config;
+    this.mode = options?.mode || "developer";
+    this.policy = {
+      allowNetwork: options?.policy?.allowNetwork ?? this.mode === "developer",
+      allowMainnet: options?.policy?.allowMainnet ?? false,
+      allowExternalWallet: options?.policy?.allowExternalWallet ?? this.mode === "developer",
+      requireDryRun: options?.policy?.requireDryRun ?? this.mode === "agent"
+    };
     this.rpc = rpc || new JsonWrpcKaspaClient({
       rpcUrl: this.resolveRpcUrl()
     });
+    this.workspace = new HardkasWorkspace(this.config.cwd);
+    this.artifacts = new HardkasArtifactsManager(this.workspace);
     this.accounts = new HardkasAccounts(this);
     this.tx = new HardkasTx(this);
     this.l2 = new HardkasL2();
     this.query = new HardkasQuery(this);
     this.localnet = new HardkasLocalnet(this);
+    this.replay = new HardkasReplay(this);
+    this.workflow = new HardkasWorkflow(this);
   }
   config;
+  workspace;
+  artifacts;
   accounts;
   tx;
   l2;
   query;
   localnet;
+  replay;
+  workflow;
+  mode;
+  policy;
   rpc;
   resolveRpcUrl() {
     const networkId = this.config.config.defaultNetwork || "simnet";
@@ -305,7 +868,7 @@ var Hardkas = class _Hardkas {
   static async open(dirOrOptions = ".") {
     const options = typeof dirOrOptions === "string" ? { cwd: dirOrOptions } : dirOrOptions;
     const loaded = await loadConfig(options);
-    return new _Hardkas(loaded);
+    return new _Hardkas(loaded, options);
   }
   /**
    * Alias for open(). Used in most examples.
@@ -325,17 +888,42 @@ var Hardkas = class _Hardkas {
   get cwd() {
     return this.config.cwd;
   }
+  /**
+   * Validates an action against the active security policy.
+   * Throws HardkasError if the policy is violated.
+   */
+  enforcePolicy(action, context) {
+    if (this.mode === "developer") return;
+    const msg = (policy) => `Agent Mode Policy Violation: '${action}' is restricted by policy '${policy}'. ${context || ""}`;
+    switch (action) {
+      case "network":
+        if (!this.policy.allowNetwork) throw new HardkasError2("POLICY_VIOLATION", msg("allowNetwork"));
+        break;
+      case "mainnet":
+        if (!this.policy.allowMainnet) throw new HardkasError2("POLICY_VIOLATION", msg("allowMainnet"));
+        break;
+      case "external-wallet":
+        if (!this.policy.allowExternalWallet) throw new HardkasError2("POLICY_VIOLATION", msg("allowExternalWallet"));
+        break;
+      case "mutation":
+        if (this.policy.requireDryRun) throw new HardkasError2("POLICY_VIOLATION", msg("requireDryRun"));
+        break;
+    }
+  }
 };
 export {
-  ARTIFACT_SCHEMAS,
-  HARDKAS_VERSION2 as HARDKAS_VERSION,
+  ARTIFACT_SCHEMAS2 as ARTIFACT_SCHEMAS,
+  HARDKAS_VERSION3 as HARDKAS_VERSION,
   Hardkas,
   HardkasAccounts,
-  HardkasError,
+  HardkasArtifactsManager,
+  HardkasError3 as HardkasError,
   HardkasL2,
   HardkasLocalnet,
   HardkasQuery,
+  HardkasReplay,
   HardkasTx,
+  HardkasWorkspace,
   SOMPI_PER_KAS,
   buildPaymentPlan2 as buildPaymentPlan,
   createTxPlanArtifact2 as createTxPlanArtifact,
@@ -344,5 +932,5 @@ export {
   formatSompi2 as formatSompi,
   parseKasToSompi2 as parseKasToSompi,
   signTxPlanArtifact2 as signTxPlanArtifact,
-  writeArtifact2 as writeArtifact
+  writeArtifact3 as writeArtifact
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/sdk",
-  "version": "0.5.4-alpha",
+  "version": "0.6.0-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -12,21 +12,22 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
-    "@hardkas/artifacts": "0.5.4-alpha",
-    "@hardkas/accounts": "0.5.4-alpha",
-    "@hardkas/config": "0.5.4-alpha",
-    "@hardkas/core": "0.5.4-alpha",
-    "@hardkas/kaspa-rpc": "0.5.4-alpha",
-    "@hardkas/l2": "0.5.4-alpha",
-    "@hardkas/simulator": "0.5.4-alpha",
-    "@hardkas/query": "0.5.4-alpha",
-    "@hardkas/tx-builder": "0.5.4-alpha",
-    "@hardkas/wallet-adapter": "0.5.4-alpha",
-    "@hardkas/localnet": "0.5.4-alpha"
+    "@hardkas/artifacts": "0.6.0-alpha",
+    "@hardkas/config": "0.6.0-alpha",
+    "@hardkas/accounts": "0.6.0-alpha",
+    "@hardkas/query": "0.6.0-alpha",
+    "@hardkas/simulator": "0.6.0-alpha",
+    "@hardkas/kaspa-rpc": "0.6.0-alpha",
+    "@hardkas/localnet": "0.6.0-alpha",
+    "@hardkas/l2": "0.6.0-alpha",
+    "@hardkas/tx-builder": "0.6.0-alpha",
+    "@hardkas/wallet-adapter": "0.6.0-alpha",
+    "@hardkas/core": "0.6.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",