@hardkas/testing 0.2.2-alpha → 0.3.0-alpha

package/dist/adversarial-fixtures.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Generates artifacts with semantic or structural flaws for adversarial testing.
+ */
+declare const AdversarialFixtures: {
+    /**
+     * Circular lineage: A -> B -> A
+     */
+    circularLineage(): {
+        artifactA: any;
+        artifactB: any;
+    };
+    /**
+     * Artifact where the contentHash does not match the actual content calculation.
+     */
+    hashMismatch(): any;
+    /**
+     * Artifact with a parent from a different network (Security Violation).
+     */
+    crossNetworkLineage(): {
+        parent: any;
+        child: any;
+    };
+    /**
+     * Trace with duplicate event IDs (Corruption).
+     */
+    duplicateEventTrace(): {
+        schema: string;
+        workflowId: string;
+        events: {
+            eventId: string;
+            kind: string;
+        }[];
+    };
+    /**
+     * Malformed JSONL snippet (truncated).
+     */
+    malformedJsonl(): string;
+    /**
+     * Lineage with sequence rollback (corrupted history).
+     */
+    sequenceRollback(): ({
+        artifactId: string;
+        lineage: {
+            sequenceId: number;
+            contentHash: string;
+            parentArtifactId?: never;
+        };
+        schema: string;
+        version: string;
+        networkId: string;
+        mode: string;
+    } | {
+        artifactId: string;
+        lineage: {
+            sequenceId: number;
+            contentHash: string;
+            parentArtifactId: string;
+        };
+        schema: string;
+        version: string;
+        networkId: string;
+        mode: string;
+    })[];
+    /**
+     * Artifact with a future timestamp (anomaly).
+     * Intentionally uses Date.now() to generate a timestamp far in the future.
+     */
+    futureTimestamp(): {
+        schema: string;
+        version: string;
+        artifactId: string;
+        contentHash: string;
+        networkId: string;
+        mode: string;
+        createdAt: string;
+    };
+    /**
+     * Artifact with an unsupported version.
+     */
+    unsupportedVersion(): {
+        schema: string;
+        version: string;
+        artifactId: string;
+        contentHash: string;
+        networkId: string;
+        mode: string;
+    };
+};
+
+export { AdversarialFixtures };

package/dist/adversarial-fixtures.js

@@ -0,0 +1,6 @@
+import {
+  AdversarialFixtures
+} from "./chunk-3EK7ATR5.js";
+export {
+  AdversarialFixtures
+};

package/dist/chunk-3EK7ATR5.js

@@ -0,0 +1,152 @@
+// src/adversarial-fixtures.ts
+import { calculateContentHash, CURRENT_HASH_VERSION, ARTIFACT_VERSION } from "@hardkas/artifacts";
+var AdversarialFixtures = {
+  /**
+   * Circular lineage: A -> B -> A
+   */
+  circularLineage() {
+    const artifactA = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "art-a",
+      contentHash: "hash-a",
+      networkId: "simnet",
+      mode: "simulated",
+      lineage: { parentArtifactId: "art-b" }
+    };
+    const artifactB = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "art-b",
+      contentHash: "hash-b",
+      networkId: "simnet",
+      mode: "simulated",
+      lineage: { parentArtifactId: "art-a" }
+    };
+    return { artifactA, artifactB };
+  },
+  /**
+   * Artifact where the contentHash does not match the actual content calculation.
+   */
+  hashMismatch() {
+    const artifact = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      networkId: "simnet",
+      mode: "simulated",
+      amountSompi: "1000",
+      estimatedFeeSompi: "1",
+      estimatedMass: "1",
+      from: { address: "kaspasim:qz0s9xrz5y5e8dq5azmpg756aeepm6fesq82ye7wv" },
+      to: { address: "kaspasim:qq0d6h0prjm5mpdld5pncst3adu0yam6xch9fkr6eg" },
+      inputs: [],
+      outputs: [],
+      hashVersion: CURRENT_HASH_VERSION
+    };
+    const realHash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
+    artifact.contentHash = "f" + realHash.slice(1);
+    artifact.artifactId = `plan-${artifact.contentHash.slice(0, 16)}`;
+    artifact.planId = artifact.artifactId;
+    return artifact;
+  },
+  /**
+   * Artifact with a parent from a different network (Security Violation).
+   */
+  crossNetworkLineage() {
+    const parent = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "parent-mainnet",
+      contentHash: "hash-mainnet",
+      networkId: "mainnet",
+      mode: "l1-rpc"
+    };
+    const child = {
+      schema: "hardkas.signedTx",
+      version: ARTIFACT_VERSION,
+      artifactId: "child-simnet",
+      contentHash: "hash-simnet",
+      networkId: "simnet",
+      mode: "simulated",
+      lineage: {
+        artifactId: "hash-simnet",
+        parentArtifactId: "parent-mainnet",
+        lineageId: "b".repeat(64),
+        rootArtifactId: "c".repeat(64)
+      }
+    };
+    return { parent, child };
+  },
+  /**
+   * Trace with duplicate event IDs (Corruption).
+   */
+  duplicateEventTrace() {
+    return {
+      schema: "hardkas.trace",
+      workflowId: "wf-1",
+      events: [
+        { eventId: "ev-1", kind: "start" },
+        { eventId: "ev-1", kind: "step" }
+        // Duplicate ID
+      ]
+    };
+  },
+  /**
+   * Malformed JSONL snippet (truncated).
+   */
+  malformedJsonl() {
+    return `{"eventId":"ev-1","kind":"start"}
+{"eventId":"ev-2","kind":"step",`;
+  },
+  /**
+   * Lineage with sequence rollback (corrupted history).
+   */
+  sequenceRollback() {
+    const common = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      networkId: "simnet",
+      mode: "simulated"
+    };
+    return [
+      { ...common, artifactId: "art-1", lineage: { sequenceId: 1, contentHash: "hash-1" } },
+      { ...common, artifactId: "art-2", lineage: { sequenceId: 2, contentHash: "hash-2", parentArtifactId: "art-1" } },
+      { ...common, artifactId: "art-3", lineage: { sequenceId: 2, contentHash: "hash-3-BAD", parentArtifactId: "art-1" } }
+      // Duplicate sequenceId 2
+    ];
+  },
+  /**
+   * Artifact with a future timestamp (anomaly).
+   * Intentionally uses Date.now() to generate a timestamp far in the future.
+   */
+  futureTimestamp() {
+    const farFuture = new Date(Date.now() + 1e3 * 60 * 60 * 24 * 365 * 10).toISOString();
+    return {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "art-future",
+      contentHash: "hash-future",
+      networkId: "simnet",
+      mode: "simulated",
+      createdAt: farFuture
+    };
+  },
+  /**
+   * Artifact with an unsupported version.
+   */
+  unsupportedVersion() {
+    return {
+      schema: "hardkas.txPlan",
+      version: "99.9.9",
+      // Future version
+      artifactId: "art-vnext",
+      contentHash: "hash-vnext",
+      networkId: "simnet",
+      mode: "simulated"
+    };
+  }
+};
+
+export {
+  AdversarialFixtures
+};

package/dist/chunk-CUJL53GG.js

@@ -0,0 +1,90 @@
+// src/harness.ts
+import {
+  createInitialLocalnetState,
+  applySimulatedPayment,
+  getAccountBalanceSompi,
+  createLocalnetSnapshot
+} from "@hardkas/localnet";
+var massRecords = [];
+var massTrackingEnabled = false;
+function enableMassTracking() {
+  massTrackingEnabled = true;
+}
+function disableMassTracking() {
+  massTrackingEnabled = false;
+}
+function getMassRecords() {
+  return [...massRecords];
+}
+function clearMassRecords() {
+  massRecords = [];
+}
+function createTestHarness(config) {
+  const accountCount = config?.accounts ?? 3;
+  const initialBalanceSompi = config?.initialBalance ?? 100000000000n;
+  let currentState = createInitialLocalnetState({
+    accounts: accountCount,
+    initialBalanceSompi
+  });
+  if (config?.networkId) {
+    currentState.networkId = config.networkId;
+  }
+  const initialState = structuredClone(currentState);
+  const harness = {
+    get state() {
+      return currentState;
+    },
+    send(opts) {
+      const preBalance = {
+        from: getAccountBalanceSompi(currentState, opts.from),
+        to: getAccountBalanceSompi(currentState, opts.to)
+      };
+      const result = applySimulatedPayment(currentState, opts);
+      if (result.ok) {
+        currentState = result.state;
+      }
+      const postBalance = {
+        from: getAccountBalanceSompi(currentState, opts.from),
+        to: getAccountBalanceSompi(currentState, opts.to)
+      };
+      if (result.ok && massTrackingEnabled && result.planArtifact) {
+        massRecords.push({
+          txId: result.receipt.txId,
+          inputCount: result.planArtifact.inputs.length,
+          outputCount: result.planArtifact.outputs.length,
+          estimatedMass: BigInt(result.planArtifact.estimatedMass),
+          estimatedFeeSompi: BigInt(result.planArtifact.estimatedFeeSompi),
+          timestamp: Date.now()
+        });
+      }
+      return {
+        ok: result.ok,
+        receipt: result.receipt,
+        plan: result.planArtifact,
+        preBalance,
+        postBalance
+      };
+    },
+    balanceOf(name) {
+      return getAccountBalanceSompi(currentState, name);
+    },
+    accountNames() {
+      return currentState.accounts.map((a) => a.name);
+    },
+    snapshot() {
+      return createLocalnetSnapshot(currentState);
+    },
+    reset() {
+      currentState = structuredClone(initialState);
+    }
+  };
+  return harness;
+}
+
+export {
+  enableMassTracking,
+  disableMassTracking,
+  getMassRecords,
+  clearMassRecords,
+  createTestHarness
+};

package/dist/chunk-UHH25II3.js

@@ -0,0 +1,103 @@
+// src/setup.ts
+import { expect } from "vitest";
+
+// src/matchers.ts
+var hardKasMatchers = {
+  toBeAccepted(received) {
+    const pass = received?.status === "accepted";
+    return {
+      pass,
+      message: () => pass ? `Expected receipt NOT to be accepted, but status is "${received.status}"` : `Expected receipt to be accepted, but status is "${received?.status ?? "undefined"}"`
+    };
+  },
+  toBeFailed(received) {
+    const pass = received?.status === "failed";
+    return {
+      pass,
+      message: () => pass ? `Expected receipt NOT to be failed, but status is "failed"` : `Expected receipt to be failed, but status is "${received?.status ?? "undefined"}"`
+    };
+  },
+  toHaveValidTxId(received) {
+    const txId = received?.txId || (typeof received === "string" ? received : "");
+    const pass = typeof txId === "string" && (txId.startsWith("simtx_") || /^[0-9a-fA-F]{64}$/.test(txId));
+    return {
+      pass,
+      message: () => pass ? `Expected "${txId}" NOT to be a valid txId` : `Expected "${txId}" to be a valid txId (starts with "simtx_" or is 64-char hex)`
+    };
+  },
+  toHaveValidContentHash(received) {
+    const hash = received?.contentHash || (typeof received === "string" ? received : "");
+    const pass = typeof hash === "string" && /^[0-9a-fA-F]{64}$/.test(hash);
+    return {
+      pass,
+      message: () => pass ? `Expected "${hash}" NOT to be a valid content hash` : `Expected "${hash}" to be a valid content hash (64-char hex)`
+    };
+  },
+  toPassLineageCheck(received) {
+    const pass = Array.isArray(received?.lineage) && received.lineage.length > 0;
+    return {
+      pass,
+      message: () => pass ? `Expected artifact NOT to pass lineage check` : `Expected artifact to pass lineage check (missing or empty lineage)`
+    };
+  },
+  toBeBlueBlock(received) {
+    const pass = received?.isBlue === true;
+    return {
+      pass,
+      message: () => pass ? `Expected block NOT to be blue, but it is` : `Expected block to be blue, but it is red or unknown`
+    };
+  },
+  toBeRedBlock(received) {
+    const pass = received?.isBlue === false;
+    return {
+      pass,
+      message: () => pass ? `Expected block NOT to be red, but it is` : `Expected block to be red, but it is blue or unknown`
+    };
+  },
+  toHaveIncreasedBy(received, amount) {
+    const actual = BigInt(received);
+    const pass = actual >= amount;
+    return {
+      pass,
+      message: () => pass ? `Expected increase NOT to be at least ${amount}, but got ${actual}` : `Expected increase to be at least ${amount}, but got ${actual}`
+    };
+  },
+  toHaveDecreasedBy(received, amount) {
+    const actual = BigInt(received);
+    const pass = actual >= amount;
+    return {
+      pass,
+      message: () => pass ? `Expected decrease NOT to be at least ${amount}, but got ${actual}` : `Expected decrease to be at least ${amount}, but got ${actual}`
+    };
+  },
+  toHaveNoRedBlocks(received) {
+    const redBlocks = Object.values(received?.blocks || {}).filter((b) => b.isBlue === false);
+    const pass = redBlocks.length === 0;
+    return {
+      pass,
+      message: () => pass ? `Expected DAG to have red blocks, but it has none` : `Expected DAG to have no red blocks, but found ${redBlocks.length}`
+    };
+  },
+  toHaveDagWidth(received, width) {
+    const allBlockIds = Object.keys(received?.blocks || {});
+    const parentIds = /* @__PURE__ */ new Set();
+    for (const block of Object.values(received?.blocks || {})) {
+      for (const p of block.parents) {
+        parentIds.add(p);
+      }
+    }
+    const tips = allBlockIds.filter((id) => !parentIds.has(id));
+    const pass = tips.length === width;
+    return {
+      pass,
+      message: () => pass ? `Expected DAG NOT to have width ${width}, but it does` : `Expected DAG to have width ${width}, but got ${tips.length}`
+    };
+  }
+};
+
+// src/setup.ts
+expect.extend(hardKasMatchers);
+
+export {
+  hardKasMatchers
+};

package/dist/chunk-WIN7YDBM.js

@@ -0,0 +1,108 @@
+import {
+  createTestHarness
+} from "./chunk-CUJL53GG.js";
+
+// src/reproducibility.ts
+import { calculateContentHash } from "@hardkas/artifacts";
+import { runLinearChain, runWideDag, profileMass } from "@hardkas/simulator";
+function generateReproducibilityReport() {
+  const l1Plan = {
+    schema: "hardkas.txPlan",
+    networkId: "simnet",
+    mode: "simulated",
+    from: { address: "kaspatest:qz0s9xrz5y5e8dq5azmpg756aeepm6fesq82ye7wv" },
+    to: { address: "kaspatest:qq0d6h0prjm5mpdld5pncst3adu0yam6xch9fkr6eg" },
+    amountSompi: "100000000",
+    inputs: [
+      { outpoint: { transactionId: "a".repeat(64), index: 0 }, amountSompi: "200000000" }
+    ],
+    outputs: [
+      { address: "kaspatest:qq0d6h0prjm5mpdld5pncst3adu0yam6xch9fkr6eg", amountSompi: "100000000" },
+      { address: "kaspatest:qz0s9xrz5y5e8dq5azmpg756aeepm6fesq82ye7wv", amountSompi: "99998000" }
+    ],
+    estimatedMass: "2000",
+    estimatedFeeSompi: "2000"
+  };
+  const l1Signed = {
+    schema: "hardkas.signedTx",
+    networkId: "simnet",
+    mode: "simulated",
+    rawTransaction: "0".repeat(128),
+    inputs: l1Plan.inputs,
+    outputs: l1Plan.outputs,
+    mass: "2000",
+    feeSompi: "2000"
+  };
+  const igraPlan = {
+    schema: "hardkas.igraTxPlan.v1",
+    networkId: "simnet",
+    mode: "l2-rpc",
+    l2Network: "igra-devnet",
+    chainId: 42069,
+    request: {
+      from: "0x1234567890123456789012345678901234567890",
+      to: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+      data: "0x",
+      valueWei: "1000000000000000000"
+    },
+    status: "built"
+  };
+  const linearResult = runLinearChain({ name: "repro-linear", blockCount: 10 });
+  const wideResult = runWideDag({ name: "repro-wide", blockCount: 10, k: 18 });
+  const linearTotal = linearResult.metrics.blueBlocks + linearResult.metrics.redBlocks;
+  const linearRedPpm = linearTotal > 0 ? Math.trunc(linearResult.metrics.redBlocks * 1e6 / linearTotal) : 0;
+  const wideTotal = wideResult.metrics.blueBlocks + wideResult.metrics.redBlocks;
+  const wideRedPpm = wideTotal > 0 ? Math.trunc(wideResult.metrics.redBlocks * 1e6 / wideTotal) : 0;
+  const massResult = profileMass({ inputCount: 3, outputCount: 2, payloadBytes: 0, feeRate: 1n });
+  const nestedObj = {
+    z: { b: 2, a: 1 },
+    y: [3, 1, 2],
+    x: null,
+    w: "test",
+    v: 123456789012345678901234567890n
+  };
+  const harness = createTestHarness({ accounts: 3, initialBalance: 100000000000n });
+  const names = harness.accountNames();
+  const txResult = harness.send({
+    from: names[0],
+    to: names[1],
+    amountSompi: 10000000000n
+  });
+  return {
+    proofVersion: "repro-v0",
+    hardkasVersion: "0.3.0-alpha",
+    artifacts: {
+      l1Plan: calculateContentHash(l1Plan),
+      l1Signed: calculateContentHash(l1Signed),
+      igraPlan: calculateContentHash(igraPlan),
+      dagLinearScenario: calculateContentHash({
+        totalBlocks: linearResult.metrics.totalBlocks,
+        blueBlocks: linearResult.metrics.blueBlocks,
+        redBlocks: linearResult.metrics.redBlocks,
+        redRatioPpm: linearRedPpm,
+        selectedChainLength: linearResult.metrics.selectedChainLength
+      }),
+      dagWideScenario: calculateContentHash({
+        totalBlocks: wideResult.metrics.totalBlocks,
+        blueBlocks: wideResult.metrics.blueBlocks,
+        redBlocks: wideResult.metrics.redBlocks,
+        redRatioPpm: wideRedPpm
+      }),
+      massProfile: calculateContentHash({
+        totalMass: massResult.totalMass.toString(),
+        inputMass: massResult.inputMass.toString(),
+        outputMass: massResult.outputMass.toString(),
+        estimatedFeeSompi: massResult.estimatedFeeSompi.toString()
+      }),
+      canonicalNested: calculateContentHash(nestedObj),
+      simulatedTxReceipt: txResult.ok ? calculateContentHash({
+        status: txResult.receipt.status,
+        txId: txResult.receipt.txId
+      }) : "TX_FAILED"
+    }
+  };
+}
+
+export {
+  generateReproducibilityReport
+};

package/dist/harness.d.ts

@@ -0,0 +1,55 @@
+import { LocalnetState } from '@hardkas/localnet';
+
+interface HarnessConfig {
+    accounts?: number | undefined;
+    initialBalance?: bigint | undefined;
+    networkId?: string | undefined;
+    ghostdagK?: number | undefined;
+}
+interface TestHarness {
+    /** The current localnet state. */
+    state: LocalnetState;
+    /** Send KAS from one account to another. Returns the receipt. */
+    send(opts: {
+        from: string;
+        to: string;
+        amountSompi: bigint;
+    }): SendResult;
+    /** Get balance of an account by name (e.g., "alice"). */
+    balanceOf(name: string): bigint;
+    /** Get all account names. */
+    accountNames(): string[];
+    /** Take a snapshot of current state. */
+    snapshot(): any;
+    /** Reset to initial state. */
+    reset(): void;
+}
+interface SendResult {
+    ok: boolean;
+    receipt: any;
+    plan: any;
+    preBalance: {
+        from: bigint;
+        to: bigint;
+    };
+    postBalance: {
+        from: bigint;
+        to: bigint;
+    };
+}
+interface MassRecord {
+    testName?: string;
+    txId: string;
+    inputCount: number;
+    outputCount: number;
+    estimatedMass: bigint;
+    estimatedFeeSompi: bigint;
+    timestamp: number;
+}
+declare function enableMassTracking(): void;
+declare function disableMassTracking(): void;
+declare function getMassRecords(): MassRecord[];
+declare function clearMassRecords(): void;
+declare function createTestHarness(config?: HarnessConfig): TestHarness;
+
+export { type HarnessConfig, type MassRecord, type SendResult, type TestHarness, clearMassRecords, createTestHarness, disableMassTracking, enableMassTracking, getMassRecords };

package/dist/harness.js

@@ -0,0 +1,14 @@
+import {
+  clearMassRecords,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  getMassRecords
+} from "./chunk-CUJL53GG.js";
+export {
+  clearMassRecords,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  getMassRecords
+};

package/dist/index.d.ts

@@ -1,25 +1,100 @@
-import { MockKaspaRpcClient } from '@hardkas/kaspa-rpc';
+import { TestHarness } from './harness.js';
+export { HarnessConfig, SendResult, clearMassRecords, createTestHarness, disableMassTracking, enableMassTracking, getMassRecords } from './harness.js';
+export { ReproducibilityReport, generateReproducibilityReport } from './reproducibility.js';
+export { AdversarialFixtures } from './adversarial-fixtures.js';
+import '@hardkas/localnet';
 
-interface TestWallet {
-    readonly name: string;
-    readonly address: string;
+interface FixtureDefinition {
+    name: string;
+    accounts?: number;
+    initialBalance?: bigint;
+    /** Pre-run transactions to set up state. */
+    setup?: Array<{
+        from: string;
+        to: string;
+        amountSompi: bigint;
+    }>;
 }
-interface HardkasTestContext {
-    readonly wallets: {
-        readonly alice: TestWallet;
-        readonly bob: TestWallet;
-        readonly carol: TestWallet;
-        readonly faucet: TestWallet;
-    };
-    readonly rpc: MockKaspaRpcClient;
-    readonly faucet: {
-        fund(address: string, amountSompi: bigint): Promise<void>;
-    };
-    reset(): Promise<void>;
+/**
+ * Create a fixture — a pre-configured harness with setup transactions already applied.
+ */
+declare function createFixture(def: FixtureDefinition): TestHarness;
+
+interface HardKasMatchers<R = void> {
+    /** Assert a receipt has status "accepted". */
+    toBeAccepted(): R;
+    /** Assert a receipt has status "failed". */
+    toBeFailed(): R;
+    /** Assert a receipt contains a valid txId (starts with "simtx_" or is 64-char hex). */
+    toHaveValidTxId(): R;
+    /** Assert an artifact has a valid contentHash (64-char hex). */
+    toHaveValidContentHash(): R;
+    /** Assert an artifact passes lineage verification. */
+    toPassLineageCheck(): R;
+    /** Assert a GHOSTDAG result colors this block as blue. */
+    toBeBlueBlock(): R;
+    /** Assert a GHOSTDAG result colors this block as red. */
+    toBeRedBlock(): R;
+    /** Assert a balance (bigint sompi) increased by at least `amount`. */
+    toHaveIncreasedBy(amount: bigint): R;
+    /** Assert a balance (bigint sompi) decreased by at least `amount`. */
+    toHaveDecreasedBy(amount: bigint): R;
+    /** Assert a simulated DAG has no red blocks. */
+    toHaveNoRedBlocks(): R;
+    /** Assert a simulated DAG has exactly N tips. */
+    toHaveDagWidth(width: number): R;
+}
+declare module "vitest" {
+    interface Assertion<T = any> extends HardKasMatchers<T> {
+    }
+    interface AsymmetricMatchersContaining extends HardKasMatchers {
+    }
 }
-declare function createHardkasTestContext(): Promise<HardkasTestContext>;
-declare const hardkas: {
-    localnet: typeof createHardkasTestContext;
+declare const hardKasMatchers: {
+    toBeAccepted(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toBeFailed(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveValidTxId(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveValidContentHash(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toPassLineageCheck(received: any): {
+        pass: boolean;
+        message: () => "Expected artifact NOT to pass lineage check" | "Expected artifact to pass lineage check (missing or empty lineage)";
+    };
+    toBeBlueBlock(received: any): {
+        pass: boolean;
+        message: () => "Expected block NOT to be blue, but it is" | "Expected block to be blue, but it is red or unknown";
+    };
+    toBeRedBlock(received: any): {
+        pass: boolean;
+        message: () => "Expected block NOT to be red, but it is" | "Expected block to be red, but it is blue or unknown";
+    };
+    toHaveIncreasedBy(received: any, amount: bigint): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveDecreasedBy(received: any, amount: bigint): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveNoRedBlocks(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveDagWidth(received: any, width: number): {
+        pass: boolean;
+        message: () => string;
+    };
 };
 
-export { type HardkasTestContext, type TestWallet, createHardkasTestContext, hardkas };
+export { type FixtureDefinition, type HardKasMatchers, TestHarness, createFixture, hardKasMatchers };

package/dist/index.js

@@ -1,50 +1,45 @@
-// src/index.ts
-import { MockKaspaRpcClient } from "@hardkas/kaspa-rpc";
-import { createDeterministicAccounts } from "@hardkas/localnet";
-import { createMockUtxo } from "@hardkas/tx-builder";
-async function createHardkasTestContext() {
-  const rpc = new MockKaspaRpcClient("simnet");
-  const accounts = createDeterministicAccounts({
-    count: 4,
-    initialBalanceSompi: 0n
-  });
-  const alice = accounts[0];
-  const bob = accounts[1];
-  const carol = accounts[2];
-  if (!alice || !bob || !carol) {
-    throw new Error("Failed to create deterministic test accounts.");
-  }
-  const wallets = {
-    alice: { name: alice.name, address: alice.address },
-    bob: { name: bob.name, address: bob.address },
-    carol: { name: carol.name, address: carol.address },
-    faucet: { name: "faucet", address: "kaspa:sim_faucet" }
+import {
+  AdversarialFixtures
+} from "./chunk-3EK7ATR5.js";
+import {
+  generateReproducibilityReport
+} from "./chunk-WIN7YDBM.js";
+import {
+  clearMassRecords,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  getMassRecords
+} from "./chunk-CUJL53GG.js";
+import {
+  hardKasMatchers
+} from "./chunk-UHH25II3.js";
+
+// src/fixtures.ts
+function createFixture(def) {
+  const config = {
+    accounts: def.accounts,
+    initialBalance: def.initialBalance
   };
-  return {
-    wallets,
-    rpc,
-    faucet: {
-      async fund(address, amountSompi) {
-        rpc.setUtxos(address, [
-          createMockUtxo({
-            address,
-            amountSompi,
-            index: 0
-          })
-        ]);
+  const harness = createTestHarness(config);
+  if (def.setup) {
+    for (const tx of def.setup) {
+      const result = harness.send(tx);
+      if (!result.ok) {
+        throw new Error(`Fixture "${def.name}" failed during setup: ${tx.from} -> ${tx.to} (${tx.amountSompi} sompi). Error: ${result.receipt?.errors?.join(", ") || "Unknown error"}`);
       }
-    },
-    async reset() {
-      rpc.setUtxos(wallets.alice.address, []);
-      rpc.setUtxos(wallets.bob.address, []);
-      rpc.setUtxos(wallets.carol.address, []);
     }
-  };
+  }
+  return harness;
 }
-var hardkas = {
-  localnet: createHardkasTestContext
-};
 export {
-  createHardkasTestContext,
-  hardkas
+  AdversarialFixtures,
+  clearMassRecords,
+  createFixture,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  generateReproducibilityReport,
+  getMassRecords,
+  hardKasMatchers
 };

package/dist/mass-setup.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/mass-setup.js

@@ -0,0 +1,8 @@
+import {
+  enableMassTracking
+} from "./chunk-CUJL53GG.js";
+
+// src/mass-setup.ts
+if (process.env.HARDKAS_MASS_TRACKING === "1") {
+  enableMassTracking();
+}

package/dist/reproducibility.d.ts

@@ -0,0 +1,24 @@
+interface ReproducibilityReport {
+    /** Fixed proof version — does NOT change between releases. */
+    proofVersion: "repro-v0";
+    /** Informational only — NOT part of hash comparison. */
+    hardkasVersion: string;
+    artifacts: {
+        l1Plan: string;
+        l1Signed: string;
+        igraPlan: string;
+        dagLinearScenario: string;
+        dagWideScenario: string;
+        massProfile: string;
+        canonicalNested: string;
+        simulatedTxReceipt: string;
+    };
+}
+/**
+ * Generate the reproducibility report.
+ * This function MUST be fully deterministic.
+ * Same code version → same output → always → everywhere.
+ */
+declare function generateReproducibilityReport(): ReproducibilityReport;
+
+export { type ReproducibilityReport, generateReproducibilityReport };

package/dist/reproducibility.js

@@ -0,0 +1,7 @@
+import {
+  generateReproducibilityReport
+} from "./chunk-WIN7YDBM.js";
+import "./chunk-CUJL53GG.js";
+export {
+  generateReproducibilityReport
+};

package/dist/setup.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/setup.js

@@ -0,0 +1 @@
+import "./chunk-UHH25II3.js";

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@hardkas/testing",
-  "version": "0.2.2-alpha",
+  "version": "0.3.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/index.js",
+    "./harness": "./dist/harness.js",
+    "./setup": "./dist/setup.js",
+    "./adversarial-fixtures": "./dist/adversarial-fixtures.js",
+    "./mass-setup": "./dist/mass-setup.js"
   },
   "dependencies": {
-    "@hardkas/artifacts": "0.2.2-alpha",
-    "@hardkas/core": "0.2.2-alpha",
-    "@hardkas/kaspa-rpc": "0.2.2-alpha",
-    "@hardkas/simulator": "0.2.2-alpha",
-    "@hardkas/localnet": "0.2.2-alpha",
-    "@hardkas/tx-builder": "0.2.2-alpha"
+    "@hardkas/artifacts": "0.3.0-alpha",
+    "@hardkas/kaspa-rpc": "0.3.0-alpha",
+    "@hardkas/localnet": "0.3.0-alpha",
+    "@hardkas/core": "0.3.0-alpha",
+    "@hardkas/tx-builder": "0.3.0-alpha",
+    "@hardkas/query-store": "0.3.0-alpha",
+    "@hardkas/simulator": "0.3.0-alpha",
+    "@hardkas/sdk": "0.3.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -37,8 +43,9 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "test": "vitest run",
+    "build": "tsup src/index.ts src/harness.ts src/setup.ts src/reproducibility.ts src/adversarial-fixtures.ts src/mass-setup.ts --format esm --dts --clean --external vitest",
+    "test": "vitest run && pnpm test:gauntlet",
+    "test:gauntlet": "node --import tsx --test test/gauntlet.node.ts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint ."
   }